X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=6e82864a0187ed7dfc0034d0d5e0518fe1f51ac4;hb=b036eb057efda11259400d3d204c1e48c9755de8;hp=1a0822c8feb376d1cfd1157b2a18aedcc192f569;hpb=de3876b815c9f095f557fe8bd6ee7c22d842c974;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 1a0822c8f..6e82864a0 100644 --- a/support/doc/api/openapi.yaml +++ b/support/doc/api/openapi.yaml @@ -1,15 +1,15 @@ openapi: 3.0.0 info: title: PeerTube - version: 3.1.0 + version: 3.2.0-rc.1 contact: name: PeerTube Community - url: 'https://joinpeertube.org' + url: https://joinpeertube.org license: name: AGPLv3.0 - url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE' + url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE x-logo: - url: 'https://joinpeertube.org/img/brand.png' + url: https://joinpeertube.org/img/brand.png altText: PeerTube Project Homepage description: | The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite @@ -27,8 +27,8 @@ info: # Authentication When you sign up for an account on a PeerTube instance, you are given the possibility - to generate sessions on it, and authenticate there using a session token. Only __one - session token can currently be used at a time__. + to generate sessions on it, and authenticate there using an access token. Only __one + access token can currently be used at a time__. ## Roles @@ -38,41 +38,60 @@ info: # Errors The API uses standard HTTP status codes to indicate the success or failure - of the API call. The body of the response will be JSON in the following - formats. + of the API call. ``` + HTTP 1.1 404 Not Found + Content-Type: application/json + { - "error": "Account not found" // error debug message + "errorCode": 1 + "error": "Account not found" } ``` - Some errors benefit from a more detailed message: + We provide error codes for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts), + but it is still optional. + + ### Validation errors + + Each parameter is evaluated on its own against a set of rules before the route validator + proceeds with potential testing involving parameter combinations. Errors coming from Validation + errors appear earlier and benefit from a more detailed error type: + ``` + HTTP 1.1 400 Bad Request + Content-Type: application/json + { "errors": { - "id": { // where 'id' is the name of the parameter concerned by the error. - "value": "a117eb-c6a9-4756-bb09-2a956239f", // value that triggered the error. - "msg": "Should have an valid id", // error debug message + "id": { // + "value": "a117eb-c6a9-4756-bb09-2a956239f", + "msg": "Should have a valid id", "param": "id", - "location": "params" // 'params', 'body', 'header', 'query' or 'cookies' + "location": "params" } } } ``` + Where `id` is the name of the field concerned by the error, within the route definition. + `errors..location` can be either 'params', 'body', 'header', 'query' or 'cookies', and + `errors..value` reports the value that didn't pass validation whose `errors..msg` + is about. + # Rate limits We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators: - | Endpoint | Calls | Time frame | - |-------------------------|------------------|---------------------------| - | `/*` | 50 | 10 seconds | - | `POST /users/token` | 15 | 5 minutes | - | `POST /users/register` | 2¹ | 5 minutes | - | `POST /users/ask-send-verify-email` | 3 | 5 minutes | + | Endpoint (prefix: `/api/v1`) | Calls | Time frame | + |------------------------------|---------------|--------------| + | `/*` | 50 | 10 seconds | + | `POST /users/token` | 15 | 5 minutes | + | `POST /users/register` | 2* | 5 minutes | + | `POST /users/ask-send-verify-email` | 3 | 5 minutes | - Depending on the endpoint, ¹failed requests are not taken into account. A service + Depending on the endpoint, *failed requests are not taken into account. A service limit is announced by a `429 Too Many Requests` status code. You can get details about the current state of your rate limit by reading the @@ -80,13 +99,37 @@ info: | Header | Description | |-------------------------|------------------------------------------------------------| - | X-RateLimit-Limit | Number of max requests allowed in the current time period | - | X-RateLimit-Remaining | Number of remaining requests in the current time period | - | X-RateLimit-Reset | Timestamp of end of current time period as UNIX timestamp | - | Retry-After | Seconds to delay after the first `429` is received | + | `X-RateLimit-Limit` | Number of max requests allowed in the current time period | + | `X-RateLimit-Remaining` | Number of remaining requests in the current time period | + | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp | + | `Retry-After` | Seconds to delay after the first `429` is received | + + # CORS + + This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/), + allowing cross-domain communication from the browser for some routes: + + | Endpoint | + |------------------------- ---| + | `/api/*` | + | `/download/*` | + | `/lazy-static/*` | + | `/live/segments-sha256/*` | + | `/.well-known/webfinger` | + + In addition, all routes serving ActivityPub are CORS-enabled for all origins. externalDocs: url: https://docs.joinpeertube.org/api-rest-reference.html tags: + - name: Register + description: | + As a visitor, you can use this API to open an account (if registrations are open on + that PeerTube instance). As an admin, you should use the dedicated [User creation + API](#operation/createUser) instead. + - name: Session + x-displayName: Login/Logout + description: | + Sessions deal with access tokens over time. Only __one session token can currently be used at a time__. - name: Accounts description: > Accounts encompass remote accounts discovered across the federation, @@ -210,6 +253,10 @@ tags: For importing videos as your own, refer to [video imports](#operation/importVideo). x-tagGroups: + - name: Auth + tags: + - Register + - Session - name: Accounts tags: - Accounts @@ -557,6 +604,7 @@ paths: /users: post: summary: Create a user + operationId: createUser security: - OAuth2: - admin @@ -673,11 +721,92 @@ paths: schema: $ref: '#/components/schemas/UpdateUser' required: true + + /oauth-clients/local: + get: + summary: Login prerequisite + description: You need to retrieve a client id and secret before [logging in](#operation/getOauthToken). + operationId: getOAuthClient + tags: + - Session + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/OAuthClient' + links: + UseOAuthClientToLogin: + operationId: getOAuthToken + parameters: + client_id: '$response.body#/client_id' + client_secret: '$response.body#/client_secret' + /users/token: + post: + summary: Login + operationId: getOAuthToken + description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens. + tags: + - Session + requestBody: + content: + application/x-www-form-urlencoded: + schema: + oneOf: + - $ref: '#/components/schemas/OAuthToken-password' + - $ref: '#/components/schemas/OAuthToken-refresh_token' + discriminator: + propertyName: grant_type + mapping: + password: '#/components/schemas/OAuthToken-password' + refresh_token: '#/components/schemas/OAuthToken-refresh_token' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + properties: + token_type: + type: string + example: Bearer + access_token: + type: string + example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0 + description: valid for 1 day + refresh_token: + type: string + example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7 + description: valid for 2 weeks + expires_in: + type: integer + minimum: 0 + example: 14399 + refresh_token_expires_in: + type: integer + minimum: 0 + example: 1209600 + /users/revoke-token: + post: + summary: Logout + description: Revokes your access token and its associated refresh token, destroying your current session. + operationId: revokeOAuthToken + tags: + - Session + security: + - OAuth2: [] + responses: + '200': + description: successful operation + /users/register: post: summary: Register a user tags: - Users + - Register responses: '204': description: successful operation @@ -687,6 +816,47 @@ paths: schema: $ref: '#/components/schemas/RegisterUser' required: true + /users/{id}/verify-email: + post: + summary: Verify a user + description: | + Following a user registration, the new user will receive an email asking to click a link + containing a secret. + tags: + - Users + - Register + parameters: + - $ref: '#/components/parameters/id' + requestBody: + content: + application/json: + schema: + type: object + properties: + verificationString: + type: string + format: url + isPendingEmail: + type: boolean + required: + - verificationString + responses: + '204': + description: successful operation + '403': + description: invalid verification string + '404': + description: user not found + /users/ask-send-verify-email: + post: + summary: Resend user verification link + tags: + - Users + - Register + responses: + '204': + description: successful operation + /users/me: get: summary: Get my user information @@ -1317,7 +1487,7 @@ paths: type: string support: description: A text tell the audience how to support the video creator - example: Please support my work on ! <3 + example: Please support our work on https://soutenir.framasoft.org/en/ <3 type: string nsfw: description: Whether or not this video contains sensitive content @@ -1672,75 +1842,7 @@ paths: content: multipart/form-data: schema: - type: object - properties: - torrentfile: - description: Torrent File - type: string - format: binary - targetUrl: - description: HTTP target URL - type: string - magnetUri: - description: Magnet URI - type: string - channelId: - description: Channel id that will contain this video - type: integer - thumbnailfile: - description: Video thumbnail file - type: string - format: binary - previewfile: - description: Video preview file - type: string - format: binary - privacy: - $ref: '#/components/schemas/VideoPrivacySet' - category: - $ref: '#/components/schemas/VideoCategorySet' - licence: - $ref: '#/components/schemas/VideoLicenceSet' - language: - $ref: '#/components/schemas/VideoLanguageSet' - description: - description: Video description - type: string - waitTranscoding: - description: Whether or not we wait transcoding before publish the video - type: boolean - support: - description: A text tell the audience how to support the video creator - example: Please support my work on ! <3 - type: string - nsfw: - description: Whether or not this video contains sensitive content - type: boolean - name: - description: Video name - type: string - minLength: 3 - maxLength: 120 - tags: - description: Video tags (maximum 5 tags each between 2 and 30 characters) - type: array - minItems: 1 - maxItems: 5 - items: - type: string - minLength: 2 - maxLength: 30 - commentsEnabled: - description: Enable or disable comments for this video - type: boolean - downloadEnabled: - description: Enable or disable downloading for this video - type: boolean - scheduleUpdate: - $ref: '#/components/schemas/VideoScheduledUpdate' - required: - - channelId - - name + $ref: '#/components/schemas/VideoCreateImport' encoding: torrentfile: contentType: application/x-bittorrent @@ -1815,7 +1917,7 @@ paths: type: string support: description: A text tell the audience how to support the creator - example: Please support my work on ! <3 + example: Please support our work on https://soutenir.framasoft.org/en/ <3 type: string nsfw: description: Whether or not this live video/replay contains sensitive content @@ -2043,10 +2145,12 @@ paths: - $ref: '#/components/schemas/Video/properties/id' startAt: type: integer + format: seconds description: Timestamp in the video that marks the beginning of the report minimum: 0 endAt: type: integer + format: seconds description: Timestamp in the video that marks the ending of the report minimum: 0 comment: @@ -2317,6 +2421,7 @@ paths: /video-channels: get: summary: List video channels + operationId: getVideoChannels tags: - Video Channels parameters: @@ -2332,6 +2437,7 @@ paths: $ref: '#/components/schemas/VideoChannelList' post: summary: Create a video channel + operationId: createVideoChannel security: - OAuth2: [] tags: @@ -2339,6 +2445,16 @@ paths: responses: '204': description: successful operation + content: + application/json: + schema: + type: object + properties: + videoChannel: + type: object + properties: + id: + $ref: '#/components/schemas/VideoChannel/properties/id' requestBody: content: application/json: @@ -2347,6 +2463,7 @@ paths: '/video-channels/{channelHandle}': get: summary: Get a video channel + operationId: getVideoChannel tags: - Video Channels parameters: @@ -2618,13 +2735,13 @@ paths: thumbnailfile: contentType: image/jpeg - /video-playlists/{id}: + /video-playlists/{playlistId}: get: summary: Get a video playlist tags: - Video Playlists parameters: - - $ref: '#/components/parameters/idOrUUID' + - $ref: '#/components/parameters/playlistId' responses: '200': description: successful operation @@ -2643,7 +2760,7 @@ paths: '204': description: successful operation parameters: - - $ref: '#/components/parameters/idOrUUID' + - $ref: '#/components/parameters/playlistId' requestBody: content: multipart/form-data: @@ -2678,19 +2795,19 @@ paths: tags: - Video Playlists parameters: - - $ref: '#/components/parameters/idOrUUID' + - $ref: '#/components/parameters/playlistId' responses: '204': description: successful operation - /video-playlists/{id}/videos: + /video-playlists/{playlistId}/videos: get: summary: 'List videos of a playlist' tags: - Videos - Video Playlists parameters: - - $ref: '#/components/parameters/idOrUUID' + - $ref: '#/components/parameters/playlistId' responses: '200': description: successful operation @@ -2699,14 +2816,14 @@ paths: schema: $ref: '#/components/schemas/VideoListResponse' post: - summary: 'Add a video in a playlist' + summary: Add a video in a playlist security: - OAuth2: [] tags: - Videos - Video Playlists parameters: - - $ref: '#/components/parameters/idOrUUID' + - $ref: '#/components/parameters/playlistId' responses: '200': description: successful operation @@ -2720,6 +2837,7 @@ paths: properties: id: type: integer + example: 2 requestBody: content: application/json: @@ -2727,19 +2845,22 @@ paths: type: object properties: videoId: - allOf: + oneOf: + - $ref: '#/components/schemas/Video/properties/uuid' - $ref: '#/components/schemas/Video/properties/id' description: Video to add in the playlist startTimestamp: type: integer - description: Start the video at this specific timestamp (in seconds) + format: seconds + description: Start the video at this specific timestamp stopTimestamp: type: integer - description: Stop the video at this specific timestamp (in seconds) + format: seconds + description: Stop the video at this specific timestamp required: - videoId - /video-playlists/{id}/videos/reorder: + /video-playlists/{playlistId}/videos/reorder: post: summary: 'Reorder a playlist' security: @@ -2747,7 +2868,7 @@ paths: tags: - Video Playlists parameters: - - $ref: '#/components/parameters/idOrUUID' + - $ref: '#/components/parameters/playlistId' responses: '204': description: successful operation @@ -2773,15 +2894,15 @@ paths: - startPosition - insertAfterPosition - /video-playlists/{id}/videos/{playlistElementId}: + /video-playlists/{playlistId}/videos/{playlistElementId}: put: - summary: 'Update a playlist element' + summary: Update a playlist element security: - OAuth2: [] tags: - Video Playlists parameters: - - $ref: '#/components/parameters/idOrUUID' + - $ref: '#/components/parameters/playlistId' - $ref: '#/components/parameters/playlistElementId' responses: '204': @@ -2794,18 +2915,20 @@ paths: properties: startTimestamp: type: integer - description: 'Start the video at this specific timestamp (in seconds)' + format: seconds + description: Start the video at this specific timestamp stopTimestamp: type: integer - description: 'Stop the video at this specific timestamp (in seconds)' + format: seconds + description: Stop the video at this specific timestamp delete: - summary: 'Delete an element from a playlist' + summary: Delete an element from a playlist security: - OAuth2: [] tags: - Video Playlists parameters: - - $ref: '#/components/parameters/idOrUUID' + - $ref: '#/components/parameters/playlistId' - $ref: '#/components/parameters/playlistElementId' responses: '204': @@ -2813,7 +2936,7 @@ paths: '/users/me/video-playlists/videos-exist': get: - summary: 'Check video exists in my playlists' + summary: Check video exists in my playlists security: - OAuth2: [] tags: @@ -2846,8 +2969,10 @@ paths: type: integer startTimestamp: type: integer + format: seconds stopTimestamp: type: integer + format: seconds '/accounts/{name}/video-channels': get: @@ -2943,8 +3068,10 @@ paths: type: object properties: text: - type: string - description: 'Text comment' + allOf: + - $ref: '#/components/schemas/VideoComment/properties/text' + format: markdown + maxLength: 10000 required: - text @@ -2989,7 +3116,10 @@ paths: type: object properties: text: - $ref: '#/components/schemas/VideoComment/properties/text' + allOf: + - $ref: '#/components/schemas/VideoComment/properties/text' + format: markdown + maxLength: 10000 required: - text @@ -3020,6 +3150,19 @@ paths: - Video Rates parameters: - $ref: '#/components/parameters/idOrUUID' + requestBody: + content: + application/json: + schema: + type: object + properties: + rating: + type: string + enum: + - like + - dislike + required: + - rating responses: '204': description: successful operation @@ -4020,6 +4163,13 @@ components: oneOf: - $ref: '#/components/schemas/id' - $ref: '#/components/schemas/UUIDv4' + playlistId: + name: playlistId + in: path + required: true + description: Playlist id + schema: + $ref: '#/components/schemas/VideoPlaylist/properties/id' playlistElementId: name: playlistElementId in: path @@ -4229,17 +4379,18 @@ components: description: | Authenticating via OAuth requires the following steps: - Have an activated account - - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a - Bearer Token for that account at `/api/v1/users/token` - - Make authenticated requests, putting *Authorization: Bearer * + - [Generate] an access token for that account at `/api/v1/users/token`. + - Make requests with the *Authorization: Bearer * header - Profit, depending on the role assigned to the account - Note that the __access token is valid for 1 day__ and, and is given + 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 type: oauth2 flows: password: - tokenUrl: 'https://peertube.example.com/api/v1/users/token' + tokenUrl: /api/v1/users/token scopes: admin: Admin scope moderator: Moderator scope @@ -4259,20 +4410,21 @@ components: maxLength: 36 username: type: string - description: The username of the user + description: immutable name of the user, used to find or mention its actor example: chocobozzz - pattern: '/^[a-z0-9._]{1,50}$/' + pattern: '/^[a-z0-9._]+$/' minLength: 1 maxLength: 50 usernameChannel: type: string - description: The username for the default channel - example: The Capybara Channel - pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/' + description: immutable name of the channel, used to interact with its actor + example: framasoft_videos + pattern: '/^[a-zA-Z0-9\\-_.:]+$/' + minLength: 1 + maxLength: 50 password: type: string format: password - description: The password of the user minLength: 6 maxLength: 255 @@ -4425,6 +4577,7 @@ components: `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos. example: 240 VideoResolutionConstant: + description: resolutions and their labels for the video properties: id: $ref: '#/components/schemas/VideoResolutionSet' @@ -4483,21 +4636,28 @@ components: type: integer startTimestamp: type: integer + format: seconds stopTimestamp: type: integer + format: seconds video: nullable: true allOf: - $ref: '#/components/schemas/Video' VideoFile: + readOnly: true properties: magnetUri: type: string + format: uri + description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file + example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4 + pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i resolution: $ref: '#/components/schemas/VideoResolutionConstant' size: type: integer - description: 'Video file size in bytes' + description: Video file size in bytes torrentUrl: type: string description: Direct URL of the torrent file @@ -4516,9 +4676,11 @@ components: format: url fps: type: number + description: Frames per second of the video file metadataUrl: type: string format: url + description: URL dereferencing the output of ffprobe on the file VideoStreamingPlaylists: allOf: - type: object @@ -4626,6 +4788,7 @@ components: duration: type: integer example: 1419 + format: seconds description: duration of the video in seconds isLocal: type: boolean @@ -4694,7 +4857,7 @@ components: support: type: string description: A text tell the audience how to support the video creator - example: Please support my work on ! <3 + example: Please support our work on https://soutenir.framasoft.org/en/ <3 minLength: 3 maxLength: 1000 channel: @@ -4719,6 +4882,9 @@ components: items: type: string format: url + example: + - https://peertube2.cpy.re/tracker/announce + - wss://peertube2.cpy.re/tracker/socket files: type: array items: @@ -4796,32 +4962,72 @@ components: label: type: string example: Pending + VideoCreateImport: + allOf: + - type: object + additionalProperties: false + oneOf: + - properties: + targetUrl: + $ref: '#/components/schemas/VideoImport/properties/targetUrl' + required: [targetUrl] + - properties: + magnetUri: + $ref: '#/components/schemas/VideoImport/properties/magnetUri' + required: [magnetUri] + - properties: + torrentfile: + $ref: '#/components/schemas/VideoImport/properties/torrentfile' + required: [torrentfile] + - $ref: '#/components/schemas/VideoUploadRequestCommon' + required: + - channelId + - name VideoImport: properties: id: - $ref: '#/components/schemas/id' + readOnly: true + allOf: + - $ref: '#/components/schemas/id' targetUrl: type: string format: url + description: remote URL where to find the import's source video example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d magnetUri: type: string format: uri + description: magnet URI allowing to resolve the import's source video example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4 + pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i + torrentfile: + writeOnly: true + type: string + format: binary + description: Torrent file containing only the video file torrentName: + readOnly: true type: string state: - $ref: '#/components/schemas/VideoImportStateConstant' + readOnly: true + allOf: + - $ref: '#/components/schemas/VideoImportStateConstant' error: + readOnly: true type: string createdAt: + readOnly: true type: string format: date-time updatedAt: + readOnly: true type: string format: date-time video: - $ref: '#/components/schemas/Video' + readOnly: true + nullable: true + allOf: + - $ref: '#/components/schemas/Video' VideoImportsList: properties: total: @@ -4948,13 +5154,16 @@ components: format: url text: type: string - description: Text of the comment in Markdown + format: html + description: Text of the comment minLength: 1 - maxLength: 10000 + example: This video is wonderful! threadId: - type: integer - inReplyToCommentId: $ref: '#/components/schemas/id' + inReplyToCommentId: + nullable: true + allOf: + - $ref: '#/components/schemas/id' videoId: $ref: '#/components/schemas/Video/properties/id' createdAt: @@ -4963,6 +5172,14 @@ components: updatedAt: type: string format: date-time + deletedAt: + nullable: true + type: string + format: date-time + default: null + isDeleted: + type: boolean + default: false totalRepliesFromVideoAuthor: type: integer minimum: 0 @@ -5020,16 +5237,24 @@ components: type: string format: url name: - type: string + description: immutable name of the actor, used to find or mention it + allOf: + - $ref: '#/components/schemas/username' host: type: string format: hostname + description: server on which the actor is resident hostRedundancyAllowed: type: boolean + description: whether this actor's host allows redundancy of its videos followingCount: type: integer + minimum: 0 + description: number of actors subscribed to by this actor, as seen by this instance followersCount: type: integer + minimum: 0 + description: number of followers of this actor, as seen by this instance createdAt: type: string format: date-time @@ -5043,15 +5268,22 @@ components: - $ref: '#/components/schemas/Actor' - properties: userId: - $ref: '#/components/schemas/id' + description: object id for the user tied to this account + allOf: + - $ref: '#/components/schemas/User/properties/id' displayName: type: string + description: editable name of the account, displayed in its representations + minLength: 3 + maxLength: 120 description: type: string + description: text or bio displayed on the account's profile UserWatchingVideo: properties: currentTime: type: integer + format: seconds description: timestamp within the video, in seconds example: 5 ServerConfig: @@ -5566,7 +5798,7 @@ components: type: boolean support: description: A text tell the audience how to support the video creator - example: Please support my work on ! <3 + example: Please support our work on https://soutenir.framasoft.org/en/ <3 type: string nsfw: description: Whether or not this video contains sensitive content @@ -5698,7 +5930,8 @@ components: type: boolean description: Has the user confirmed their email address? id: - type: integer + allOf: + - $ref: '#/components/schemas/id' readOnly: true pluginAuth: type: string @@ -5794,9 +6027,9 @@ components: UpdateUser: properties: email: - type: string - format: email description: The updated email of the user + allOf: + - $ref: '#/components/schemas/User/properties/email' emailVerified: type: boolean description: Set the email as verified @@ -5816,28 +6049,54 @@ components: adminFlags: $ref: '#/components/schemas/UserAdminFlags' UpdateMe: + # see shared/models/users/user-update-me.model.ts: properties: password: $ref: '#/components/schemas/password' + currentPassword: + $ref: '#/components/schemas/password' email: + description: new email used for login and service communications + allOf: + - $ref: '#/components/schemas/User/properties/email' + displayName: type: string - format: email - description: Your new email + description: new name of the user in its representations + minLength: 3 + maxLength: 120 displayNSFW: type: string - description: Your new displayNSFW + description: new NSFW display policy enum: - 'true' - 'false' - both + webTorrentEnabled: + type: boolean + description: whether to enable P2P in the player or not autoPlayVideo: type: boolean - description: Your new autoPlayVideo - required: - - password - - email - - displayNSFW - - autoPlayVideo + description: new preference regarding playing videos automatically + autoPlayNextVideo: + type: boolean + description: new preference regarding playing following videos automatically + autoPlayNextVideoPlaylist: + type: boolean + description: new preference regarding playing following playlist videos automatically + videosHistoryEnabled: + type: boolean + description: whether to keep track of watched history or not + videoLanguages: + type: array + items: + type: string + description: list of languages to filter videos down to + theme: + type: string + noInstanceConfigWarningModal: + type: boolean + noWelcomeModal: + type: boolean GetMeVideoRating: properties: id: @@ -5869,38 +6128,94 @@ components: RegisterUser: properties: username: - $ref: '#/components/schemas/username' + description: immutable name of the user, used to find or mention its actor + allOf: + - $ref: '#/components/schemas/username' password: $ref: '#/components/schemas/password' email: type: string format: email - description: The email of the user + description: email of the user, used for login or service communications displayName: type: string - description: The user display name + description: editable name of the user, displayed in its representations minLength: 1 maxLength: 120 channel: type: object + description: channel base information used to create the first channel of the user properties: name: $ref: '#/components/schemas/usernameChannel' displayName: - type: string - description: The display name for the default channel - minLength: 1 - maxLength: 120 + $ref: '#/components/schemas/VideoChannel/properties/displayName' required: - username - password - email + OAuthClient: + properties: + client_id: + type: string + pattern: /^[a-z0-9]$/ + maxLength: 32 + minLength: 32 + example: v1ikx5hnfop4mdpnci8nsqh93c45rldf + client_secret: + type: string + pattern: /^[a-zA-Z0-9]$/ + maxLength: 32 + minLength: 32 + example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt + OAuthToken-password: + allOf: + - $ref: '#/components/schemas/OAuthClient' + - type: object + properties: + grant_type: + type: string + enum: + - password + - refresh_token + default: password + username: + $ref: '#/components/schemas/User/properties/username' + password: + $ref: '#/components/schemas/password' + required: + - client_id + - client_secret + - grant_type + - username + - password + OAuthToken-refresh_token: + allOf: + - $ref: '#/components/schemas/OAuthClient' + - type: object + properties: + grant_type: + type: string + enum: + - password + - refresh_token + default: password + refresh_token: + type: string + example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7 + required: + - client_id + - client_secret + - grant_type + - refresh_token + VideoChannel: properties: # GET/POST/PUT properties displayName: type: string + description: editable name of the channel, displayed in its representations example: Videos of Framasoft minLength: 1 maxLength: 120 @@ -5912,7 +6227,7 @@ components: support: type: string description: text shown by default on all videos of this channel, to tell the audience how to support it - example: Please support my work on ! <3 + example: Please support our work on https://soutenir.framasoft.org/en/ <3 minLength: 3 maxLength: 1000 # GET-only properties @@ -6225,9 +6540,7 @@ components: type: string nullable: true magnetUri: - type: string - format: uri - nullable: true + $ref: '#/components/schemas/VideoImport/properties/magnetUri' targetUri: type: string format: uri