Fix broken playlist api

[github/Chocobozzz/PeerTube.git] / support / doc / api / openapi.yaml

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index c1a9a3987b7f94430f1bcda0c41f7890e028cad8..39fa3cef51fa20af5044696aeb61ac7f0aa094c1 100644 (file)
--- 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.3.0-rc.2
+  version: 1.3.1
   contact:
     name: PeerTube Community
     url: 'https://joinpeertube.org'
@@ -38,7 +38,7 @@ info:
     }
     ```
 externalDocs:
-  url: https://docs.joinpeertube.org/#/api-rest-reference.html
+  url: https://docs.joinpeertube.org/api-rest-reference.html
 tags:
   - name: Accounts
     description: >
@@ -96,6 +96,7 @@ x-tagGroups:
     tags:
       - Accounts
       - User
+      - My User
   - name: Videos
     tags:
       - Video
@@ -153,7 +154,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Video'
+                $ref: '#/components/schemas/VideoListResponse'
       x-code-samples:
         - lang: JavaScript
           source: |
@@ -489,6 +490,20 @@ paths:
             schema:
               $ref: '#/components/schemas/UpdateUser'
         required: true
+  /users/register:
+    post:
+      summary: Register a user
+      tags:
+        - User
+      responses:
+        '204':
+          $ref: '#/paths/~1users~1me/put/responses/204'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterUser'
+        required: true
   /users/me:
     get:
       summary: Get current user information
@@ -496,7 +511,7 @@ paths:
         - OAuth2:
           - user
       tags:
-        - User
+        - My User
       responses:
         '200':
           description: successful operation
@@ -512,7 +527,7 @@ paths:
         - OAuth2:
           - user
       tags:
-        - User
+        - My User
       responses:
         '204':
           description: Successful operation
@@ -522,6 +537,25 @@ paths:
             schema:
               $ref: '#/components/schemas/UpdateMe'
         required: true
+  /users/me/videos/imports:
+    get:
+      summary: Get video imports of current user
+      security:
+        - OAuth2:
+            - user
+      tags:
+        - My User
+      parameters:
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/sort'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoImport'
   /users/me/video-quota-used:
     get:
       summary: Get current user used quota
@@ -529,7 +563,7 @@ paths:
         - OAuth2:
           - user
       tags:
-        - User
+        - My User
       responses:
         '200':
           description: successful operation
@@ -543,7 +577,7 @@ paths:
       security:
         - OAuth2: []
       tags:
-        - User
+        - My User
       parameters:
         - name: videoId
           in: path
@@ -565,7 +599,7 @@ paths:
         - OAuth2:
           - user
       tags:
-        - User
+        - My User
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -576,9 +610,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
@@ -586,7 +618,7 @@ paths:
         - OAuth2:
             - user
       tags:
-        - User
+        - My User
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -600,7 +632,7 @@ paths:
         - OAuth2:
             - user
       tags:
-        - User
+        - My User
       responses:
         '200':
           description: successful operation
@@ -611,7 +643,7 @@ paths:
         - OAuth2:
             - user
       tags:
-        - User
+        - My User
       parameters:
         - $ref: '#/components/parameters/subscriptionsUris'
       responses:
@@ -628,7 +660,7 @@ paths:
         - OAuth2:
           - user
       tags:
-        - User
+        - My User
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -639,17 +671,17 @@ 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:
         - OAuth2:
             - user
       tags:
-        - User
+        - My User
+      parameters:
+        - $ref: '#/components/parameters/subscriptionHandle'
       responses:
         '200':
           description: successful operation
@@ -663,31 +695,19 @@ paths:
         - OAuth2:
             - user
       tags:
-        - User
+        - My User
+      parameters:
+        - $ref: '#/components/parameters/subscriptionHandle'
       responses:
         '200':
           description: successful operation
-  /users/register:
-    post:
-      summary: Register a user
-      tags:
-        - User
-      responses:
-        '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/RegisterUser'
-        required: true
   /users/me/avatar/pick:
     post:
       summary: Update current user avatar
       security:
         - OAuth2: []
       tags:
-        - User
+        - My User
       responses:
         '200':
           description: successful operation
@@ -731,12 +751,10 @@ 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
+      summary: Get list of video categories known by the server
       tags:
         - Video
       responses:
@@ -798,7 +816,7 @@ paths:
       tags:
         - Video
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '200':
           description: successful operation
@@ -850,34 +868,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:
@@ -885,7 +890,7 @@ paths:
       tags:
         - Video
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -895,7 +900,7 @@ paths:
       tags:
         - Video
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '200':
           description: successful operation
@@ -909,7 +914,7 @@ paths:
       tags:
         - Video
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -921,7 +926,7 @@ paths:
       security:
         - OAuth2: []
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       requestBody:
         content:
           application/json:
@@ -938,8 +943,6 @@ paths:
         - Video
       security:
         - OAuth2: []
-      parameters:
-        - $ref: '#/components/parameters/id2'
       responses:
         '200':
           description: successful operation
@@ -951,7 +954,7 @@ paths:
       security:
         - OAuth2: []
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -963,7 +966,7 @@ paths:
       security:
         - OAuth2: []
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -975,7 +978,7 @@ paths:
       security:
         - OAuth2: []
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       requestBody:
         required: true
         content:
@@ -1059,7 +1062,8 @@ paths:
                 commentsEnabled:
                   description: Enable or disable comments for this video
                   type: string
-                scheduleUpdate: *ref_0
+                scheduleUpdate:
+                  $ref: '#/components/schemas/VideoScheduledUpdate'
               required:
                 - videofile
                 - channelId
@@ -1163,7 +1167,8 @@ paths:
                 commentsEnabled:
                   description: Enable or disable comments for this video
                   type: string
-                scheduleUpdate: *ref_0
+                scheduleUpdate:
+                  $ref: '#/components/schemas/VideoScheduledUpdate'
               required:
                 - channelId
                 - name
@@ -1195,7 +1200,7 @@ paths:
       tags:
         - Video Abuse
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -1209,7 +1214,7 @@ paths:
       tags:
         - Video Blacklist
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -1222,7 +1227,7 @@ paths:
       tags:
         - Video Blacklist
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -1254,7 +1259,7 @@ paths:
       tags:
         - Video Caption
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '200':
           description: successful operation
@@ -1275,7 +1280,7 @@ paths:
       tags:
         - Video Caption
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/captionLanguage'
       requestBody:
         content:
@@ -1295,7 +1300,7 @@ paths:
       tags:
         - Video Caption
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/captionLanguage'
       responses:
         '204':
@@ -1328,7 +1333,10 @@ paths:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
       requestBody:
-        $ref: '#/components/requestBodies/VideoChannelInput'
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VideoChannelCreate'
   '/video-channels/{channelHandle}':
     get:
       summary: Get a video channel by its id
@@ -1355,7 +1363,10 @@ paths:
         '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:
@@ -1371,6 +1382,7 @@ paths:
     get:
       summary: Get videos of a video channel by its id
       tags:
+        - Video
         - Video Channel
       parameters:
         - $ref: '#/components/parameters/channelHandle'
@@ -1380,7 +1392,7 @@ paths:
           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
@@ -1405,6 +1417,7 @@ paths:
       tags:
         - User
       parameters:
+        - $ref: '#/components/parameters/name'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/sort'
@@ -1432,7 +1445,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'
@@ -1450,7 +1463,7 @@ paths:
       tags:
         - Video Comment
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '200':
           description: successful operation
@@ -1464,13 +1477,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
@@ -1486,7 +1494,7 @@ paths:
       tags:
         - Video Comment
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/commentId'
       responses:
         '200':
@@ -1496,13 +1504,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':
@@ -1515,7 +1523,7 @@ paths:
       tags:
         - Video Rate
       parameters:
-        - $ref: '#/components/parameters/id2'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
           $ref: '#/paths/~1users~1me/put/responses/204'
@@ -1540,9 +1548,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)
@@ -1657,7 +1663,7 @@ components:
       description: The user id
       schema:
         type: number
-    id2:
+    idOrUUID:
       name: id
       in: path
       required: true
@@ -1678,10 +1684,24 @@ components:
       description: "The video channel handle (example: 'my_username@example.com' or 'my_username')"
       schema:
         type: string
-    commentId:
+    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
@@ -1782,12 +1802,6 @@ components:
         type: array
         items:
           type: string
-  requestBodies:
-    VideoChannelInput:
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/VideoChannelInput'
   securitySchemes:
     OAuth2:
       description: >
@@ -1841,6 +1855,115 @@ components:
             - 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
+        video:
+          nullable: true
+          $ref: '#/components/schemas/Video'
+    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:
@@ -1853,6 +1976,8 @@ components:
           type: string
         updatedAt:
           type: string
+        originallyPublishedAt:
+          type: string
         category:
           $ref: '#/components/schemas/VideoConstantNumber'
         licence:
@@ -1883,19 +2008,99 @@ 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:
+            currentTime:
+              type: number
+    VideoDetails:
+      allOf:
+        - $ref: '#/components/schemas/Video'
+        - type: object
+          properties:
+            descriptionPath:
               type: string
-            url:
+            support:
               type: string
-            host:
+            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'
+    VideoImportStateConstant:
+      properties:
+        id:
+          type: integer
+          enum:
+            - 1
+            - 2
+            - 3
+          description: 'The video import state (Pending = 1, Success = 2, Failed = 3)'
+        label:
+          type: string
+    VideoImport:
+      properties:
+        id:
+          type: number
+        targetUrl:
+          type: string
+        magnetUri:
+          type: string
+        torrentName:
+          type: string
+        state:
+          type: object
+          properties:
+            id:
+              $ref: '#/components/schemas/VideoImportStateConstant'
+            label:
               type: string
-            avatar:
-              $ref: '#/components/schemas/Avatar'
+        error:
+          type: string
+        createdAt:
+          type: string
+        updatedAt:
+          type: string
+        video:
+          $ref: '#/components/schemas/Video'
     VideoAbuse:
       properties:
         id:
@@ -2180,6 +2385,14 @@ components:
       properties:
         comment:
           $ref: '#/components/schemas/VideoComment'
+    VideoListResponse:
+      properties:
+        total:
+          type: number
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Video'
     AddUser:
       properties:
         username:
@@ -2289,14 +2502,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'