X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=959a70438fc145dd2abe3c9548b8c028f1014bde;hb=05a60d85997c108d39bcfb14f1ffd4c74f8b1e93;hp=c2f9d424e1156240b9a34c8f9d3689ae4a1bc43a;hpb=71e3e879c0616882ee82a0e44f8c2e5ee9698a3e;p=github%2FChocobozzz%2FPeerTube.git

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index c2f9d424e..959a70438 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: 4.0.0
+  version: 5.1.0
   contact:
     name: PeerTube Community
     url: https://joinpeertube.org
@@ -21,7 +21,7 @@ info:
     - [Go](https://framagit.org/framasoft/peertube/clients/go)
     - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
 
-    See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
+    See the [REST API quick start](https://docs.joinpeertube.org/api/rest-getting-started) for a few
     examples of using the PeerTube API.
 
     # Authentication
@@ -33,7 +33,7 @@ info:
     ## Roles
 
     Accounts are given permissions based on their role. There are three roles on
-    PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin-managing-users?id=roles) for a detail of their permissions.
+    PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin/managing-users#roles) for a detail of their permissions.
 
     # Errors
 
@@ -46,7 +46,7 @@ info:
 
     {
       "detail": "Video not found",
-      "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+      "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
       "status": 404,
       "title": "Not Found",
       "type": "about:blank"
@@ -63,10 +63,10 @@ info:
 
     {
       "detail": "Cannot get this video regarding follow constraints",
-      "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+      "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
       "status": 403,
       "title": "Forbidden",
-      "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
+      "type": "https://docs.joinpeertube.org/api/rest-reference.html#section/Errors/does_not_respect_follow_constraints"
     }
     ```
 
@@ -84,7 +84,7 @@ info:
 
     {
       "detail": "Incorrect request parameters: id",
-      "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+      "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
       "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
       "invalid-params": {
         "id": {
@@ -149,7 +149,7 @@ info:
 
     In addition, all routes serving ActivityPub are CORS-enabled for all origins.
 externalDocs:
-  url: https://docs.joinpeertube.org/api-rest-reference.html
+  url: https://docs.joinpeertube.org/api/rest-reference.html
 tags:
   - name: Register
     description: |
@@ -204,7 +204,7 @@ tags:
       information across its social graph by posting activities to actors' inbox
       endpoints.
     externalDocs:
-      url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
+      url: https://docs.joinpeertube.org/admin/following-instances#instances-follows
   - name: Instance Redundancy
     description: >
       Redundancy is part of the inter-server solidarity that PeerTube fosters.
@@ -212,12 +212,12 @@ tags:
       to the policy of video selection of your choice. Note that you have a similar functionality
       to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
     externalDocs:
-      url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
+      url: https://docs.joinpeertube.org/admin/following-instances#instances-redundancy
   - name: Plugins
     description: >
       Managing plugins installed from a local path or from NPM, or search for new ones.
     externalDocs:
-      url: https://docs.joinpeertube.org/api-plugins
+      url: https://docs.joinpeertube.org/api/plugins
   - name: Abuses
     description: |
       Abuses deal with reports of local or remote videos/comments/accounts alike.
@@ -1401,22 +1401,48 @@ paths:
         '200':
           description: successful operation
 
-  /api/v1/users/register:
+  /api/v1/users/ask-send-verify-email:
     post:
-      summary: Register a user
-      operationId: registerUser
+      summary: Resend user verification link
+      operationId: resendEmailToVerifyUser
       tags:
         - Users
         - Register
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                email:
+                  type: string
+                  description: User email
+              required:
+                - email
       responses:
         '204':
           description: successful operation
+
+  /api/v1/users/registrations/ask-send-verify-email:
+    post:
+      summary: Resend verification link to registration email
+      operationId: resendEmailToVerifyRegistration
+      tags:
+        - Register
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/RegisterUser'
-        required: true
+              type: object
+              properties:
+                email:
+                  type: string
+                  description: Registration email
+              required:
+                - email
+      responses:
+        '204':
+          description: successful operation
 
   /api/v1/users/{id}/verify-email:
     post:
@@ -1425,6 +1451,7 @@ paths:
       description: |
         Following a user registration, the new user will receive an email asking to click a link
         containing a secret.
+        This endpoint can also be used to verify a new email set in the user account.
       tags:
         - Users
         - Register
@@ -1451,6 +1478,36 @@ paths:
         '404':
           description: user not found
 
+  /api/v1/users/registrations/{registrationId}/verify-email:
+    post:
+      summary: Verify a registration email
+      operationId: verifyRegistrationEmail
+      description: |
+        Following a user registration request, the user will receive an email asking to click a link
+        containing a secret.
+      tags:
+        - Register
+      parameters:
+        - $ref: '#/components/parameters/registrationId'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                verificationString:
+                  type: string
+                  format: url
+              required:
+                - verificationString
+      responses:
+        '204':
+          description: successful operation
+        '403':
+          description: invalid verification string
+        '404':
+          description: registration not found
+
   /api/v1/users/{id}/two-factor/request:
     post:
       summary: Request two factor auth
@@ -1541,18 +1598,6 @@ paths:
         '404':
           description: user not found
 
-
-  /api/v1/users/ask-send-verify-email:
-    post:
-      summary: Resend user verification link
-      operationId: resendEmailToVerifyUser
-      tags:
-        - Users
-        - Register
-      responses:
-        '204':
-          description: successful operation
-
   /api/v1/users/me:
     get:
       summary: Get my user information
@@ -2037,6 +2082,158 @@ paths:
         '204':
           description: successful operation
 
+  /api/v1/users/register:
+    post:
+      summary: Register a user
+      operationId: registerUser
+      description: Signup has to be enabled and signup approval is not required
+      tags:
+        - Register
+      responses:
+        '204':
+          description: successful operation
+        '400':
+          description: request error
+        '403':
+          description: user registration is not enabled, user limit is reached, registration is not allowed for the ip, requires approval or blocked by a plugin
+        '409':
+          description: 'a user with this username, channel name or email already exists'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterUser'
+        required: true
+
+  /api/v1/users/registrations/request:
+    post:
+      summary: Request registration
+      description: Signup has to be enabled and require approval on the instance
+      operationId: requestRegistration
+      tags:
+        - Register
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserRegistration'
+        '400':
+          description: request error or signup approval is not enabled on the instance
+        '403':
+          description: user registration is not enabled, user limit is reached, registration is not allowed for the ip or blocked by a plugin
+        '409':
+          description: 'a user or registration with this username, channel name or email already exists'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserRegistrationRequest'
+
+  /api/v1/users/registrations/{registrationId}/accept:
+    post:
+      security:
+        - OAuth2:
+          - admin
+          - moderator
+      summary: Accept registration
+      operationId: acceptRegistration
+      tags:
+        - Register
+      parameters:
+        - $ref: '#/components/parameters/registrationId'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
+      responses:
+        '204':
+          description: successful operation
+
+  /api/v1/users/registrations/{registrationId}/reject:
+    post:
+      security:
+        - OAuth2:
+          - admin
+          - moderator
+      summary: Reject registration
+      operationId: rejectRegistration
+      tags:
+        - Register
+      parameters:
+        - $ref: '#/components/parameters/registrationId'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
+      responses:
+        '204':
+          description: successful operation
+
+  /api/v1/users/registrations/{registrationId}:
+    delete:
+      security:
+        - OAuth2:
+          - admin
+          - moderator
+      summary: Delete registration
+      description: 'Delete the registration entry. It will not remove the user associated with this registration (if any)'
+      operationId: deleteRegistration
+      tags:
+        - Register
+      parameters:
+        - $ref: '#/components/parameters/registrationId'
+      responses:
+        '204':
+          description: successful operation
+
+  /api/v1/users/registrations:
+    get:
+      security:
+        - OAuth2:
+          - admin
+          - moderator
+      summary: List registrations
+      operationId: listRegistrations
+      tags:
+        - Register
+      parameters:
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - name: search
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: sort
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+            - -createdAt
+            - createdAt
+            - state
+            - -state
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/UserRegistration'
+
   /api/v1/videos/ownership:
     get:
       summary: List video ownership changes
@@ -2249,7 +2446,7 @@ paths:
   /api/v1/videos/privacies:
     get:
       summary: List available video privacy policies
-      operationId: getPrivacyPolicies
+      operationId: getVideoPrivacyPolicies
       tags:
         - Video
       responses:
@@ -2890,6 +3087,8 @@ paths:
                   type: integer
                 saveReplay:
                   type: boolean
+                replaySettings:
+                  $ref: '#/components/schemas/LiveVideoReplaySettings'
                 permanentLive:
                   description: User can stream multiple times in a permanent live
                   type: boolean
@@ -3608,6 +3807,34 @@ paths:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
 
+  '/api/v1/video-channels/{channelHandle}/video-playlists':
+    get:
+      summary: List playlists of a channel
+      tags:
+        - Video Playlists
+        - Video Channels
+      parameters:
+        - $ref: '#/components/parameters/channelHandle'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/sort'
+        - $ref: '#/components/parameters/videoPlaylistType'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/VideoPlaylist'
+
   '/api/v1/video-channels/{channelHandle}/followers':
     get:
       tags:
@@ -3852,6 +4079,7 @@ paths:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/sort'
+        - $ref: '#/components/parameters/videoPlaylistType'
       responses:
         '200':
           description: successful operation
@@ -4168,7 +4396,35 @@ paths:
                           format: seconds
                         stopTimestamp:
                           type: integer
-                          format: seconds
+
+  '/api/v1/accounts/{name}/video-playlists':
+    get:
+      summary: List playlists of an account
+      tags:
+        - Video Playlists
+        - Accounts
+      parameters:
+        - $ref: '#/components/parameters/name'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/sort'
+        - $ref: '#/components/parameters/search'
+        - $ref: '#/components/parameters/videoPlaylistType'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/VideoPlaylist'
 
   '/api/v1/accounts/{name}/video-channels':
     get:
@@ -5389,6 +5645,7 @@ components:
         type: string
         enum:
         - createdAt
+
     name:
       name: name
       in: path
@@ -5404,6 +5661,13 @@ components:
       description: Entity id
       schema:
         $ref: '#/components/schemas/id'
+    registrationId:
+      name: registrationId
+      in: path
+      required: true
+      description: Registration ID
+      schema:
+        $ref: '#/components/schemas/id'
     idOrUUID:
       name: id
       in: path
@@ -5719,7 +5983,13 @@ components:
       description: Ask the server to reinject videoFileToken in URLs in m3u8 playlist
       schema:
         type: boolean
-
+    videoPlaylistType:
+      name: playlistType
+      in: query
+      required: false
+      schema:
+        $ref: '#/components/schemas/VideoPlaylistTypeSet'
+        
   securitySchemes:
     OAuth2:
       description: |
@@ -5732,7 +6002,7 @@ components:
         Note that the __access token is valid for 1 day__ and is given
         along with a __refresh token valid for 2 weeks__.
 
-        [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
+        [Generate]: https://docs.joinpeertube.org/api/rest-getting-started
       type: oauth2
       flows:
         password:
@@ -5820,7 +6090,7 @@ components:
         - 1
         - 2
         - 3
-      description: Video playlist privacy policy (see [/video-playlists/privacies])
+      description: Video playlist privacy policy (see [/video-playlists/privacies](#operation/getPlaylistPrivacyPolicies))
     VideoPlaylistPrivacyConstant:
       properties:
         id:
@@ -5848,7 +6118,7 @@ components:
         - 2
         - 3
         - 4
-      description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
+      description: privacy id of the video (see [/videos/privacies](#operation/getVideoPrivacyPolicies))
     VideoPrivacyConstant:
       properties:
         id:
@@ -5909,6 +6179,14 @@ components:
         - 2
         - 3
       description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)'
+    
+    LiveVideoReplaySettings:
+      type: object
+      properties:
+        privacy:
+          # description: Video playlist privacy policy (see [../video-playlists/privacies])
+          $ref: '#/components/schemas/VideoPrivacySet'
+
 
     VideoStateConstant:
       properties:
@@ -7724,6 +8002,7 @@ components:
       required:
         - video
         - rating
+
     RegisterUser:
       properties:
         username:
@@ -7754,6 +8033,77 @@ components:
         - password
         - email
 
+    UserRegistrationRequest:
+      allOf:
+        - $ref: '#/components/schemas/RegisterUser'
+        - type: object
+          properties:
+            registrationReason:
+              type: string
+              description: reason for the user to register on the instance
+          required:
+            - registrationReason
+
+    UserRegistrationAcceptOrReject:
+      type: object
+      properties:
+        moderationResponse:
+          type: string
+          description: Moderation response to send to the user
+        preventEmailDelivery:
+          type: boolean
+          description: Set it to true if you don't want PeerTube to send an email to the user
+      required:
+        - moderationResponse
+
+    UserRegistration:
+      properties:
+        id:
+          $ref: '#/components/schemas/id'
+        state:
+          type: object
+          properties:
+            id:
+              type: integer
+              enum:
+                - 1
+                - 2
+                - 3
+              description: 'The registration state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
+            label:
+              type: string
+        registrationReason:
+          type: string
+        moderationResponse:
+          type: string
+          nullable: true
+        username:
+          type: string
+        email:
+          type: string
+          format: email
+        emailVerified:
+          type: boolean
+        accountDisplayName:
+          type: string
+        channelHandle:
+          type: string
+        channelDisplayName:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+        user:
+          type: object
+          nullable: true
+          description: If the registration has been accepted, this is a partial user object created by the registration
+          properties:
+            id:
+              $ref: '#/components/schemas/id'
+
     OAuthClient:
       properties:
         client_id:
@@ -7852,9 +8202,18 @@ components:
                 uuid:
                   $ref: '#/components/schemas/UUIDv4'
 
+    VideoChannelEdit:
+      properties:
+        displayName:
+          description: Channel display name
+        description:
+          description: Channel description
+        support:
+          description: How to support/fund the channel
+
     VideoChannelCreate:
       allOf:
-        - $ref: '#/components/schemas/VideoChannel'
+        - $ref: '#/components/schemas/VideoChannelEdit'
         - properties:
             name:
               description: username of the channel to create
@@ -7865,11 +8224,12 @@ components:
         - displayName
     VideoChannelUpdate:
       allOf:
-        - $ref: '#/components/schemas/VideoChannel'
+        - $ref: '#/components/schemas/VideoChannelEdit'
         - properties:
             bulkVideosSupportUpdate:
               type: boolean
               description: Update the support field for all videos of this channel
+
     VideoChannelList:
       properties:
         total:
@@ -8128,17 +8488,13 @@ components:
     NotificationSettingValue:
       type: integer
       description: >
-        Notification type
+        Notification type. One of the following values, or a sum of multiple values:
 
         - `0` NONE
 
         - `1` WEB
 
         - `2` EMAIL
-      enum:
-        - 0
-        - 1
-        - 2
     Notification:
       properties:
         id:
@@ -8347,6 +8703,8 @@ components:
       properties:
         saveReplay:
           type: boolean
+        replaySettings:
+          $ref: '#/components/schemas/LiveVideoReplaySettings'
         permanentLive:
           description: User can stream multiple times in a permanent live
           type: boolean
@@ -8367,6 +8725,8 @@ components:
           description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
         saveReplay:
           type: boolean
+        replaySettings:
+          $ref: '#/components/schemas/LiveVideoReplaySettings'
         permanentLive:
           description: User can stream multiple times in a permanent live
           type: boolean