Translated using Weblate (French (France))

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

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 6c1ffee4f0d02a70799dd1b5ecc41436c46d5272..186d7d37da81c382b83e7b6796f5b2c39352c101 100644 (file)
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -484,12 +484,30 @@ paths:
       tags:
         - Users
       responses:
-        '200':
-          description: successful operation
+        '201':
+          description: user created
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AddUserResponse'
+          links:
+            # GET /users/{id}
+            GetUserId:
+              operationId: getUserId
+              parameters:
+                id: '$response.body#/user/id'
+            # PUT /users/{id}
+            PutUserId:
+              operationId: putUserId
+              parameters:
+                id: '$response.body#/user/id'
+            # DELETE /users/{id}
+            DelUserId:
+              operationId: delUserId
+              parameters:
+                id: '$response.body#/user/id'
+        '403':
+          description: insufficient authority to create an admin or moderator
       requestBody:
         content:
           application/json:
@@ -517,6 +535,8 @@ paths:
                 items:
                   $ref: '#/components/schemas/User'
   '/users/{id}':
+    parameters:
+      - $ref: '#/components/parameters/id'
     delete:
       summary: Delete a user
       security:
@@ -524,8 +544,7 @@ paths:
             - admin
       tags:
         - Users
-      parameters:
-        - $ref: '#/components/parameters/id'
+      operationId: delUserId
       responses:
         '204':
           description: successful operation
@@ -535,8 +554,7 @@ paths:
         - OAuth2: []
       tags:
         - Users
-      parameters:
-        - $ref: '#/components/parameters/id'
+      operationId: getUserId
       responses:
         '200':
           description: successful operation
@@ -550,8 +568,7 @@ paths:
         - OAuth2: []
       tags:
         - Users
-      parameters:
-        - $ref: '#/components/parameters/id'
+      operationId: putUserId
       responses:
         '204':
           description: successful operation
@@ -701,12 +718,28 @@ paths:
         '200':
           description: successful operation
     post:
+      tags:
+        - My Subscriptions
       summary: Add subscription to my user
       security:
         - OAuth2:
             - user
-      tags:
-        - My Subscriptions
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                uri:
+                  type: string
+                  format: uri
+                  description: uri of the video channels to subscribe to
+              required:
+                - uri
+            examples:
+              default:
+                value:
+                  uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
       responses:
         '200':
           description: successful operation
@@ -816,7 +849,7 @@ paths:
         - My Notifications
       requestBody:
         content:
-          multipart/form-data:
+          application/json:
             schema:
               type: object
               properties:
@@ -849,7 +882,7 @@ paths:
         - My Notifications
       requestBody:
         content:
-          multipart/form-data:
+          application/json:
             schema:
               type: object
               properties:
@@ -1114,7 +1147,8 @@ paths:
                   description: Whether or not we wait transcoding before publish the video
                   type: string
                 support:
-                  description: Text describing how to support the video uploader
+                  description: A text tell the audience how to support the video creator
+                  example: Please support my work on <insert crowdfunding plateform>! <3
                   type: string
                 nsfw:
                   description: Whether or not this video contains sensitive content
@@ -1272,7 +1306,8 @@ paths:
                   description: Whether or not we wait transcoding before publish the video
                   type: string
                 support:
-                  description: Text describing how to support the video uploader
+                  description: A text tell the audience how to support the video creator
+                  example: Please support my work on <insert crowdfunding plateform>! <3
                   type: string
                 nsfw:
                   description: Whether or not this video contains sensitive content
@@ -1389,7 +1424,8 @@ paths:
                   description: Whether or not we wait transcoding before publish the video
                   type: string
                 support:
-                  description: Text describing how to support the video uploader
+                  description: A text tell the audience how to support the video creator
+                  example: Please support my work on <insert crowdfunding plateform>! <3
                   type: string
                 nsfw:
                   description: Whether or not this video contains sensitive content
@@ -1930,6 +1966,9 @@ paths:
                   type: integer
               required:
                 - displayName
+            encoding:
+              thumbnailfile:
+                contentType: image/jpeg
 
   /video-playlists/{id}:
     get:
@@ -1978,6 +2017,9 @@ paths:
                 videoChannelId:
                   description: Video channel in which the playlist will be published
                   type: integer
+            encoding:
+              thumbnailfile:
+                contentType: image/jpeg
     delete:
       summary: Delete a video playlist
       security:
@@ -2242,6 +2284,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'
+        '404':
+          description: video does not exist
       requestBody:
         content:
           application/json:
@@ -2286,6 +2330,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'
+        '404':
+          description: thread or video does not exist
       requestBody:
         content:
           application/json:
@@ -2328,6 +2374,8 @@ paths:
       responses:
         '204':
           description: successful operation
+        '404':
+          description: video does not exist
   /search/videos:
     get:
       tags:
@@ -2390,6 +2438,9 @@ paths:
           description: Get videos that have this maximum duration
           schema:
             type: integer
+      callbacks:
+        'searchTarget === search-index':
+          $ref: '#/components/callbacks/searchIndex'
       responses:
         '200':
           description: successful operation
@@ -2397,6 +2448,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
+        '500':
+          description: search index unavailable
   /search/video-channels:
     get:
       tags:
@@ -2416,6 +2469,9 @@ paths:
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/searchTarget'
         - $ref: '#/components/parameters/sort'
+      callbacks:
+        'searchTarget === search-index':
+          $ref: '#/components/callbacks/searchIndex'
       responses:
         '200':
           description: successful operation
@@ -2425,6 +2481,8 @@ paths:
                 type: array
                 items:
                   $ref: '#/components/schemas/VideoChannel'
+        '500':
+          description: search index unavailable
   /blocklist/accounts:
     get:
       tags:
@@ -2668,7 +2726,7 @@ paths:
         - name: format
           in: path
           required: true
-          description: 'format expected (we focus on making `rss` the most featureful ; it serves Media RSS)'
+          description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
           schema:
             type: string
             enum:
@@ -2684,6 +2742,26 @@ paths:
           description: 'limit listing to a specific video'
           schema:
             type: string
+        - name: accountId
+          in: query
+          description: 'limit listing to a specific account'
+          schema:
+            type: string
+        - name: accountName
+          in: query
+          description: 'limit listing to a specific account'
+          schema:
+            type: string
+        - name: videoChannelId
+          in: query
+          description: 'limit listing to a specific video channel'
+          schema:
+            type: string
+        - name: videoChannelName
+          in: query
+          description: 'limit listing to a specific video channel'
+          schema:
+            type: string
       responses:
         '204':
           description: successful operation
@@ -2708,6 +2786,13 @@ paths:
             application/json:
               schema:
                 type: object
+        '400':
+          x-summary: field inconsistencies
+          description: >
+            Arises when:
+              - videoId filter is mixed with a channel filter
+        '404':
+          description: video, video channel or account not found
         '406':
           description: accept header unsupported
   '/feeds/videos.{format}':
@@ -2726,7 +2811,7 @@ paths:
         - name: format
           in: path
           required: true
-          description: 'format expected (we focus on making `rss` the most featureful ; it serves Media RSS)'
+          description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
           schema:
             type: string
             enum:
@@ -2787,6 +2872,8 @@ paths:
             application/json:
               schema:
                 type: object
+        '404':
+          description: video channel or account not found
         '406':
           description: accept header unsupported
   /plugins:
@@ -3455,6 +3542,7 @@ components:
         - 1
         - 2
       description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
+      example: 2
 
     VideoStateConstant:
       properties:
@@ -3719,6 +3807,7 @@ components:
               type: string
             support:
               type: string
+              description: A text tell the audience how to support the video creator
               example: Please support my work on <insert crowdfunding plateform>! <3
             channel:
               $ref: '#/components/schemas/VideoChannel'
@@ -4481,12 +4570,18 @@ components:
           format: date-time
     AddUserResponse:
       properties:
-        id:
-          type: integer
-        uuid:
-          type: string
-          format: uuid
-          example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+        user:
+          type: object
+          properties:
+            id:
+              type: integer
+              example: 8
+            account:
+              type: object
+              properties:
+                id:
+                  type: integer
+                  example: 37
     VideoUploadResponse:
       properties:
         video:
@@ -4744,6 +4839,7 @@ components:
         support:
           type: string
           description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
+          example: Please support my work on <insert crowdfunding plateform>! <3
       required:
         - name
         - displayName
@@ -4756,6 +4852,7 @@ components:
         support:
           type: string
           description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
+          example: Please support my work on <insert crowdfunding plateform>! <3
         bulkVideosSupportUpdate:
           type: boolean
           description: 'Update the support field for all videos of this channel'
@@ -5156,4 +5253,16 @@ components:
           type: array
           maxItems: 100
           items:
-            $ref: '#/components/schemas/Plugin'
\ No newline at end of file
+            $ref: '#/components/schemas/Plugin'
+  callbacks:
+    searchIndex:
+      '{%CONFIG.SEARCH.SEARCH_INDEX.URL%}/api/v1/search/videos/':
+        post:
+          summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
+          responses:
+            '200':
+              description: successful operation
+              content:
+                application/json:
+                  schema:
+                    $ref: '#/components/schemas/VideoListResponse'
\ No newline at end of file