X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=3f887a7bb246aac667dc9df5a968da870bd6b997;hb=512a575971874a8d271ba245bbb4d02ff24a668e;hp=484cfb31daec83d0c47ca39920e3ca42521a4428;hpb=fbe1bc2afa3d57a7880a076ec3a3b21cd9b89516;p=github%2FChocobozzz%2FPeerTube.git

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 484cfb31d..3f887a7bb 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -1,7 +1,7 @@
 openapi: 3.0.0
 info:
   title: PeerTube
-  version: 1.2.1
+  version: 1.3.1
   contact:
     name: PeerTube Community
     url: 'https://joinpeertube.org'
@@ -38,7 +38,7 @@ info:
     }
     ```
 externalDocs:
-  url: https://docs.joinpeertube.org/api.html
+  url: https://docs.joinpeertube.org/api-rest-reference.html
 tags:
   - name: Accounts
     description: >
@@ -99,6 +99,7 @@ x-tagGroups:
   - name: Videos
     tags:
       - Video
+      - Video Caption
       - Video Channel
       - Video Comment
       - Video Following
@@ -152,7 +153,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
       x-code-samples:
         - lang: JavaScript
           source: |
@@ -575,9 +576,7 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
   /users/me/subscriptions:
     get:
       summary: Get subscriptions of the current user
@@ -638,10 +637,8 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Video'
-  '/users/me/subscriptions/{uri}':
+                $ref: '#/components/schemas/VideoListResponse'
+  '/users/me/subscriptions/{subscriptionHandle}':
     get:
       summary: Get subscription of the current user for a given uri
       security:
@@ -649,6 +646,8 @@ paths:
             - user
       tags:
         - User
+      parameters:
+        - $ref: '#/components/parameters/subscriptionHandle'
       responses:
         '200':
           description: successful operation
@@ -663,6 +662,8 @@ paths:
             - user
       tags:
         - User
+      parameters:
+        - $ref: '#/components/parameters/subscriptionHandle'
       responses:
         '200':
           description: successful operation
@@ -730,9 +731,7 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
   /videos/categories:
     get:
       summary: Get list of video licences known by the server
@@ -797,7 +796,7 @@ paths:
       tags:
         - Video
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '200':
           description: successful operation
@@ -849,34 +848,21 @@ paths:
                 commentsEnabled:
                   description: Enable or disable comments for this video
                   type: string
-                scheduleUpdate: &ref_0
-                  type: object
-                  properties:
-                    privacy:
-                      type: string
-                      enum:
-                        - Public
-                        - Unlisted
-                      description: Video privacy target
-                    updateAt:
-                      type: string
-                      format: date
-                      description: When to update the video
-                  required:
-                    - updateAt
+                scheduleUpdate:
+                  $ref: '#/components/schemas/VideoScheduledUpdate'
     get:
       summary: Get a video by its id
       tags:
         - Video
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoDetails'
     delete:
       summary: Delete a video by its id
       security:
@@ -884,7 +870,7 @@ paths:
       tags:
         - Video
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -894,7 +880,7 @@ paths:
       tags:
         - Video
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '200':
           description: successful operation
@@ -908,7 +894,7 @@ paths:
       tags:
         - Video
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -920,7 +906,7 @@ paths:
       security:
         - OAuth2: []
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       requestBody:
         content:
           application/json:
@@ -937,8 +923,6 @@ paths:
         - Video
       security:
         - OAuth2: []
-      parameters:
-        - $ref: '#/components/parameters/id2'
       responses:
         '200':
           description: successful operation
@@ -950,7 +934,7 @@ paths:
       security:
         - OAuth2: []
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -962,7 +946,7 @@ paths:
       security:
         - OAuth2: []
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -974,7 +958,7 @@ paths:
       security:
         - OAuth2: []
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       requestBody:
         required: true
         content:
@@ -1025,7 +1009,7 @@ paths:
                   description: Video preview file
                   type: string
                 privacy:
-                  $ref: '#/components/schemas/VideoPrivacy'
+                  $ref: '#/components/schemas/VideoPrivacySet'
                 category:
                   description: Video category
                   type: string
@@ -1058,7 +1042,8 @@ paths:
                 commentsEnabled:
                   description: Enable or disable comments for this video
                   type: string
-                scheduleUpdate: *ref_0
+                scheduleUpdate:
+                  $ref: '#/components/schemas/VideoScheduledUpdate'
               required:
                 - videofile
                 - channelId
@@ -1129,7 +1114,7 @@ paths:
                   description: Video preview file
                   type: string
                 privacy:
-                  $ref: '#/components/schemas/VideoPrivacy'
+                  $ref: '#/components/schemas/VideoPrivacySet'
                 category:
                   description: Video category
                   type: string
@@ -1162,7 +1147,8 @@ paths:
                 commentsEnabled:
                   description: Enable or disable comments for this video
                   type: string
-                scheduleUpdate: *ref_0
+                scheduleUpdate:
+                  $ref: '#/components/schemas/VideoScheduledUpdate'
               required:
                 - channelId
                 - name
@@ -1194,7 +1180,7 @@ paths:
       tags:
         - Video Abuse
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -1208,7 +1194,7 @@ paths:
       tags:
         - Video Blacklist
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -1221,7 +1207,7 @@ paths:
       tags:
         - Video Blacklist
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -1247,6 +1233,58 @@ paths:
                 type: array
                 items:
                   $ref: '#/components/schemas/VideoBlacklist'
+  /videos/{id}/captions:
+    get:
+      summary: Get list of video's captions
+      tags:
+        - Video Caption
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/VideoCaption'
+  /videos/{id}/captions/{captionLanguage}:
+    put:
+      summary: Add or replace a video caption
+      tags:
+        - Video Caption
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/captionLanguage'
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                captionfile:
+                  description: The file to upload.
+                  type: string
+                  format: binary
+      responses:
+        '204':
+          $ref: '#/paths/~1users~1me/put/responses/204'
+    delete:
+      summary: Delete a video caption
+      tags:
+        - Video Caption
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/captionLanguage'
+      responses:
+        '204':
+          $ref: '#/paths/~1users~1me/put/responses/204'
   /video-channels:
     get:
       summary: Get list of video channels
@@ -1275,14 +1313,17 @@ paths:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
       requestBody:
-        $ref: '#/components/requestBodies/VideoChannelInput'
-  '/video-channels/{id}':
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VideoChannelCreate'
+  '/video-channels/{channelHandle}':
     get:
       summary: Get a video channel by its id
       tags:
         - Video Channel
       parameters:
-        - $ref: '#/components/parameters/id3'
+        - $ref: '#/components/parameters/channelHandle'
       responses:
         '200':
           description: successful operation
@@ -1297,12 +1338,15 @@ paths:
       tags:
         - Video Channel
       parameters:
-        - $ref: '#/components/parameters/id3'
+        - $ref: '#/components/parameters/channelHandle'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
       requestBody:
-        $ref: '#/components/requestBodies/VideoChannelInput'
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VideoChannelUpdate'
     delete:
       summary: Delete a video channel by its id
       security:
@@ -1310,24 +1354,25 @@ paths:
       tags:
         - Video Channel
       parameters:
-        - $ref: '#/components/parameters/id3'
+        - $ref: '#/components/parameters/channelHandle'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
-  '/video-channels/{id}/videos':
+  '/video-channels/{channelHandle}/videos':
     get:
       summary: Get videos of a video channel by its id
       tags:
+        - Video
         - Video Channel
       parameters:
-        - $ref: '#/components/parameters/id3'
+        - $ref: '#/components/parameters/channelHandle'
       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
   '/accounts/{name}/video-channels':
     get:
       summary: Get video channels of an account by its name
@@ -1352,6 +1397,7 @@ paths:
       tags:
         - User
       parameters:
+        - $ref: '#/components/parameters/name'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/sort'
@@ -1379,7 +1425,7 @@ paths:
       tags:
         - Video Comment
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/sort'
@@ -1397,7 +1443,7 @@ paths:
       tags:
         - Video Comment
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '200':
           description: successful operation
@@ -1411,13 +1457,8 @@ paths:
       tags:
         - Video Comment
       parameters:
-        - $ref: '#/components/parameters/id2'
-        - name: threadId
-          in: path
-          required: true
-          description: The thread id (root comment id)
-          schema:
-            type: number
+        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/threadId'
       responses:
         '200':
           description: successful operation
@@ -1433,7 +1474,7 @@ paths:
       tags:
         - Video Comment
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/commentId'
       responses:
         '200':
@@ -1443,13 +1484,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'
     delete:
-      summary: 'Delete a comment in a comment therad by its id, of a video by its id'
+      summary: 'Delete a comment in a comment thread by its id, of a video by its id'
       security:
         - OAuth2: []
       tags:
         - Video Comment
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/commentId'
       responses:
         '204':
@@ -1462,7 +1503,7 @@ paths:
       tags:
         - Video Rate
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -1487,9 +1528,7 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
 servers:
   - url: 'https://peertube.cpy.re/api/v1'
     description: Live Test Server (live data - stable version)
@@ -1604,24 +1643,45 @@ components:
       description: The user id
       schema:
         type: number
-    id2:
+    idOrUUID:
       name: id
       in: path
       required: true
       description: The video id or uuid
       schema:
         type: string
-    id3:
-      name: id
+    captionLanguage:
+      name: captionLanguage
       in: path
       required: true
-      description: The video channel id or uuid
+      description: The caption language
       schema:
         type: string
-    commentId:
+    channelHandle:
+      name: channelHandle
+      in: path
+      required: true
+      description: "The video channel handle (example: 'my_username@example.com' or 'my_username')"
+      schema:
+        type: string
+    subscriptionHandle:
+      name: subscriptionHandle
+      in: path
+      required: true
+      description: "The subscription handle (example: 'my_username@example.com' or 'my_username')"
+      schema:
+        type: string
+    threadId:
       name: threadId
       in: path
       required: true
+      description: The thread id (root comment id)
+      schema:
+        type: number
+    commentId:
+      name: commentId
+      in: path
+      required: true
       description: The comment id
       schema:
         type: number
@@ -1722,12 +1782,6 @@ components:
         type: array
         items:
           type: string
-  requestBodies:
-    VideoChannelInput:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/VideoChannelInput'
   securitySchemes:
     OAuth2:
       description: >
@@ -1739,7 +1793,7 @@ components:
 
         - Have an account with sufficient authorization levels
 
-        - [Generate](https://docs.joinpeertube.org/lang/en/devdocs/rest.html) a
+        - [Generate](https://docs.joinpeertube.org/#/api-rest-getting-started) a
         Bearer Token
 
         - Make Authenticated Requests
@@ -1764,12 +1818,129 @@ components:
           type: string
         label:
           type: string
-    VideoPrivacy:
-      type: string
+    VideoPrivacySet:
+      type: integer
       enum:
-        - Public
-        - Unlisted
-        - Private
+        - 1
+        - 2
+        - 3
+      description: 'The video privacy (Public = 1, Unlisted = 2, Private = 3)'
+    VideoPrivacyConstant:
+      properties:
+        id:
+          type: integer
+          enum:
+            - 1
+            - 2
+            - 3
+        label:
+          type: string
+    VideoStateConstant:
+      properties:
+        id:
+          type: integer
+          enum:
+            - 1
+            - 2
+            - 3
+          description: 'The video state (Published = 1, to transcode = 2, to import = 3)'
+        label:
+          type: string
+    VideoResolutionConstant:
+      properties:
+        id:
+          type: integer
+          description: 'Video resolution (240, 360, 720 ...)'
+        label:
+          type: string
+    VideoScheduledUpdate:
+      properties:
+        privacy:
+          $ref: '#/components/schemas/VideoPrivacySet'
+          description: Video privacy target
+        updateAt:
+          type: string
+          format: date
+          description: When to update the video
+      required:
+        - updateAt
+    VideoAccountSummary:
+      properties:
+        id:
+          type: number
+        name:
+          type: string
+        displayName:
+          type: string
+        url:
+          type: string
+        host:
+          type: string
+        avatar:
+          nullable: true
+          $ref: '#/components/schemas/Avatar'
+    VideoChannelSummary:
+      properties:
+        id:
+          type: number
+        name:
+          type: string
+        displayName:
+          type: string
+        url:
+          type: string
+        host:
+          type: string
+        avatar:
+          nullable: true
+          $ref: '#/components/schemas/Avatar'
+    PlaylistElement:
+      properties:
+        position:
+          type: number
+        startTimestamp:
+          type: number
+        stopTimestamp:
+          type: number
+    VideoFile:
+      properties:
+        magnetUri:
+          type: string
+        resolution:
+          $ref: '#/components/schemas/VideoResolutionConstant'
+        size:
+          type: number
+          description: 'Video file size in bytes'
+        torrentUrl:
+          type: string
+        torrentDownaloadUrl:
+          type: string
+        fileUrl:
+          type: string
+        fileDownloadUrl:
+          type: string
+        fps:
+          type: number
+    VideoStreamingPlaylists:
+      properties:
+        id:
+          type: number
+        type:
+          type: number
+          enum:
+            - 1
+          description: 'Playlist type (HLS = 1)'
+        playlistUrl:
+          type: string
+        segmentsSha256Url:
+          type: string
+        redundancies:
+          type: array
+          items:
+            type: object
+            properties:
+              baseUrl:
+                type: string
     Video:
       properties:
         id:
@@ -1782,6 +1953,8 @@ components:
           type: string
         updatedAt:
           type: string
+        originallyPublishedAt:
+          type: string
         category:
           $ref: '#/components/schemas/VideoConstantNumber'
         licence:
@@ -1789,7 +1962,7 @@ components:
         language:
           $ref: '#/components/schemas/VideoConstantString'
         privacy:
-          $ref: '#/components/schemas/VideoPrivacy'
+          $ref: '#/components/schemas/VideoPrivacyConstant'
         description:
           type: string
         duration:
@@ -1812,19 +1985,66 @@ components:
           type: number
         nsfw:
           type: boolean
+        waitTranscoding:
+          type: boolean
+          nullable: true
+        state:
+          $ref: '#/components/schemas/VideoStateConstant'
+        scheduledUpdate:
+          nullable: true
+          $ref: '#/components/schemas/VideoScheduledUpdate'
+        blacklisted:
+          nullable: true
+          type: boolean
+        blacklistedReason:
+          nullable: true
+          type: string
         account:
+          $ref: '#/components/schemas/VideoAccountSummary'
+        channel:
+          $ref: '#/components/schemas/VideoChannelSummary'
+        userHistory:
+          nullable: true
           type: object
           properties:
-            name:
-              type: string
-            displayName:
-              type: string
-            url:
+            currentTime:
+              type: number
+        playlistElement:
+          nullable: true
+          $ref: '#/components/schemas/PlaylistElement'
+    VideoDetails:
+      allOf:
+        - $ref: '#/components/schemas/Video'
+        - type: object
+          properties:
+            descriptionPath:
               type: string
-            host:
+            support:
               type: string
-            avatar:
-              $ref: '#/components/schemas/Avatar'
+            channel:
+              $ref: '#/components/schemas/VideoChannel'
+            account:
+              $ref: '#/components/schemas/Account'
+            tags:
+              type: array
+              items:
+                type: string
+            files:
+              type: array
+              items:
+                $ref: '#/components/schemas/VideoFile'
+            commentsEnabled:
+              type: boolean
+            downloadEnabled:
+              type: boolean
+            trackerUrls:
+              type: array
+              items:
+                type: string
+            streamingPlaylists:
+              type: array
+              items:
+                $ref: '#/components/schemas/VideoStreamingPlaylists'
     VideoAbuse:
       properties:
         id:
@@ -1917,6 +2137,12 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/VideoCommentThreadTree'
+    VideoCaption:
+      properties:
+        language:
+          $ref: '#/components/schemas/VideoConstantString'
+        captionPath:
+          type: string
     Avatar:
       properties:
         path:
@@ -1966,6 +2192,13 @@ components:
         autoPlayVideo:
           type: boolean
         role:
+          type: integer
+          enum:
+            - 0
+            - 1
+            - 2
+          description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
+        roleLabel:
           type: string
           enum:
             - User
@@ -1973,7 +2206,7 @@ components:
             - Administrator
         videoQuota:
           type: number
-        dailyVideoQuota:
+        videoQuotaDaily:
           type: number
         createdAt:
           type: string
@@ -2096,6 +2329,14 @@ components:
       properties:
         comment:
           $ref: '#/components/schemas/VideoComment'
+    VideoListResponse:
+      properties:
+        total:
+          type: number
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Video'
     AddUser:
       properties:
         username:
@@ -2115,12 +2356,11 @@ components:
           description: 'The user daily video quota '
         role:
           type: integer
-          format: int32
           enum:
             - 0
             - 1
             - 2
-          description: 'The user role '
+          description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
       required:
         - username
         - password
@@ -2143,8 +2383,12 @@ components:
           type: string
           description: 'The updated daily video quota of the user '
         role:
-          type: string
-          description: 'The updated role of the user '
+          type: integer
+          enum:
+            - 0
+            - 1
+            - 2
+          description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
       required:
         - id
         - email
@@ -2202,14 +2446,45 @@ components:
         email:
           type: string
           description: 'The email of the user '
+        displayName:
+          type: string
+          description: 'The user display name'
+        channel:
+          type: object
+          properties:
+            name:
+              type: string
+              description: 'The default channel name'
+            displayName:
+              type: string
+              description: 'The default channel display name'
+
       required:
         - username
         - password
         - email
-    VideoChannelInput:
+    VideoChannelCreate:
       properties:
         name:
           type: string
+        displayName:
+          type: string
         description:
           type: string
+        support:
+          type: string
+      required:
+        - name
+        - displayName
+    VideoChannelUpdate:
+      properties:
+        displayName:
+          type: string
+        description:
+          type: string
+        support:
+          type: string
+        bulkVideosSupportUpdate:
+          type: boolean
+          description: 'Update all videos support field of this channel'