X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=76e78fe53a65fc12f4b51a754a18c76ed0de97d4;hb=171efc48e67498406feb6d7873b3482b41505515;hp=61fd6c95ab56c497df5838dcb118b7958bfc4d27;hpb=1e4d2cb5aef11898585fae4053da4ebd0a69b480;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 61fd6c95a..76e78fe53 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: 3.2.0-rc.1 + version: 3.3.0 contact: name: PeerTube Community url: https://joinpeertube.org @@ -22,7 +22,7 @@ info: - [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 - examples of using with the PeerTube API. + examples of using the PeerTube API. # Authentication @@ -38,48 +38,79 @@ info: # Errors The API uses standard HTTP status codes to indicate the success or failure - of the API call. + of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body. ``` HTTP 1.1 404 Not Found - Content-Type: application/json + Content-Type: application/problem+json; charset=utf-8 { - "errorCode": 1 - "error": "Account not found" + "detail": "Video not found", + "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo", + "status": 404, + "title": "Not Found", + "type": "about:blank" } ``` - 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. + We provide error `type` values 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. Types are used to disambiguate errors that bear the same status code + and are non-obvious: + + ``` + HTTP 1.1 403 Forbidden + Content-Type: application/problem+json; charset=utf-8 + + { + "detail": "Cannot get this video regarding follow constraints", + "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" + } + ``` + + Here a 403 error could otherwise mean that the video is private or blocklisted. ### 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: + proceeds with potential testing involving parameter combinations. Errors coming from validation + errors appear earlier and benefit from a more detailed error description: ``` HTTP 1.1 400 Bad Request - Content-Type: application/json + Content-Type: application/problem+json; charset=utf-8 { - "errors": { + "detail": "Incorrect request parameters: id", + "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo", + "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180", + "invalid-params": { "id": { - "value": "a117eb-c6a9-4756-bb09-2a956239f", - "msg": "Should have a valid id", + "location": "params", + "msg": "Invalid value", "param": "id", - "location": "params" + "value": "9c9de5e8-0a1e-484a-b099-e80766180" } - } + }, + "status": 400, + "title": "Bad Request", + "type": "about:blank" } ``` 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` + `invalid-params..location` can be either 'params', 'body', 'header', 'query' or 'cookies', and + `invalid-params..value` reports the value that didn't pass validation whose `invalid-params..msg` is about. + ### Deprecated error fields + + Some fields could be included with previous versions. They are still included but their use is deprecated: + - `error`: superseded by `detail` + - `code`: superseded by `type` (which is now an URI) + # Rate limits We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators: @@ -108,7 +139,7 @@ info: 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/*` | @@ -124,8 +155,8 @@ 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. + that PeerTube instance). As an admin, you should use the dedicated [User creation + API](#operation/addUser) instead. - name: Session x-displayName: Login/Logout description: | @@ -247,6 +278,8 @@ tags: Administrators can also enable the use of a remote search system, indexing videos and channels not could be not federated by the instance. + - name: Homepage + description: Get and update the custom homepage - name: Video Mirroring description: | PeerTube instances can mirror videos from one another, and help distribute some videos. @@ -281,6 +314,9 @@ x-tagGroups: - name: Search tags: - Search + - name: Custom pages + tags: + - Homepage - name: Moderation tags: - Abuses @@ -477,6 +513,40 @@ paths: '200': description: successful operation + /custom-pages/homepage/instance: + get: + summary: Get instance custom homepage + tags: + - Homepage + responses: + '404': + description: No homepage set + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/CustomHomepage' + put: + summary: Set instance custom homepage + tags: + - Homepage + security: + - OAuth2: + - admin + requestBody: + content: + application/json: + schema: + type: object + properties: + content: + type: string + description: content of the homepage, that will be injected in the client + responses: + '204': + description: successful operation + /jobs/{state}: get: summary: List instance jobs @@ -646,7 +716,7 @@ paths: - admin tags: - Instance Follows - summary: Follow a list of servers + summary: Follow a list of actors (PeerTube instance, channel or account) responses: '204': description: successful operation @@ -664,33 +734,37 @@ paths: type: string format: hostname uniqueItems: true + handles: + type: array + items: + type: string + uniqueItems: true - '/server/following/{host}': + '/server/following/{hostOrHandle}': delete: - summary: Unfollow a server + summary: Unfollow an actor (PeerTube instance, channel or account) security: - OAuth2: - admin tags: - Instance Follows parameters: - - name: host + - name: hostOrHandle in: path required: true - description: The host to unfollow + description: The hostOrHandle to unfollow schema: type: string - format: hostname responses: '204': description: successful operation '404': - description: host not found + description: host or handle not found /users: post: summary: Create a user - operationId: createUser + operationId: addUser security: - OAuth2: - admin @@ -705,18 +779,18 @@ paths: $ref: '#/components/schemas/AddUserResponse' links: # GET /users/{id} - GetUserId: - operationId: getUserId + GetUser: + operationId: getUser parameters: id: '$response.body#/user/id' # PUT /users/{id} - PutUserId: - operationId: putUserId + PutUser: + operationId: putUser parameters: id: '$response.body#/user/id' # DELETE /users/{id} - DelUserId: - operationId: delUserId + DelUser: + operationId: delUser parameters: id: '$response.body#/user/id' '403': @@ -764,7 +838,7 @@ paths: - admin tags: - Users - operationId: delUserId + operationId: delUser responses: '204': description: successful operation @@ -774,7 +848,7 @@ paths: - OAuth2: [] tags: - Users - operationId: getUserId + operationId: getUser parameters: - name: withStats in: query @@ -799,7 +873,7 @@ paths: - OAuth2: [] tags: - Users - operationId: putUserId + operationId: putUser responses: '204': description: successful operation @@ -884,6 +958,18 @@ paths: type: integer minimum: 0 example: 1209600 + '400': + x-summary: client or credentials are invalid + description: | + Disambiguate via `type`: + - `invalid_client` for an unmatched `client_id` + - `invalid_grant` for unmatched credentials + '401': + x-summary: token expired + description: | + Disambiguate via `type`: + - default value for a regular authentication failure + - `invalid_token` for an expired token x-codeSamples: - lang: Shell source: | @@ -939,7 +1025,7 @@ paths: operationId: verifyUser description: | Following a user registration, the new user will receive an email asking to click a link - containing a secret. + containing a secret. tags: - Users - Register @@ -1493,6 +1579,7 @@ paths: /videos: get: summary: List videos + operationId: getVideos tags: - Video parameters: @@ -1657,6 +1744,9 @@ paths: commentsEnabled: description: Enable or disable comments for this video type: boolean + downloadEnabled: + description: Enable or disable downloading for this video + type: boolean originallyPublishedAt: description: Date when the content was originally published type: string @@ -1719,6 +1809,7 @@ paths: '/videos/{id}/views': post: summary: Add a view to a video + operationId: addView tags: - Video parameters: @@ -1730,6 +1821,7 @@ paths: '/videos/{id}/watching': put: summary: Set watching progress of a video + operationId: setProgress tags: - Video security: @@ -1763,14 +1855,15 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' - '400': - description: invalid file field, schedule date or parameter '403': description: video didn't pass upload filter '408': description: upload has timed out '413': - description: video file too large, due to quota or max body size limit set by the reverse-proxy + x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy + description: | + If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`: + - `quota_reached` for quota limits wether daily or global headers: X-File-Maximum-Size: schema: @@ -1869,10 +1962,12 @@ paths: schema: type: number example: 0 - '400': - description: invalid file field, schedule date or parameter '413': - description: video file too large, due to quota, absolute max file size or concurrent partial upload limit + x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit + description: | + Disambiguate via `type`: + - `max_file_size_reached` for the absolute file size limit + - `quota_reached` for quota limits whether daily or global '415': description: video type unsupported put: @@ -1886,7 +1981,7 @@ paths: - Video Upload parameters: - name: upload_id - in: path + in: query required: true description: | Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is @@ -1948,10 +2043,14 @@ paths: example: 0 '403': description: video didn't pass upload filter - '413': - description: video file too large, due to quota or max body size limit set by the reverse-proxy + '404': + description: upload not found + '409': + description: chunk doesn't match range '422': description: video unreadable + '429': + description: too many concurrent requests delete: summary: Cancel the resumable upload of a video, deleting any data uploaded so far description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video @@ -1963,7 +2062,7 @@ paths: - Video Upload parameters: - name: upload_id - in: path + in: query required: true description: | Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is @@ -1984,6 +2083,8 @@ paths: schema: type: number example: 0 + '404': + description: upload not found /videos/imports: post: @@ -2024,7 +2125,7 @@ paths: /videos/live: post: summary: Create a live - operationId: createLive + operationId: addLive security: - OAuth2: [] tags: @@ -2037,8 +2138,20 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' + '400': + x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set + description: | + Disambiguate via `type`: + - default type for a validation error + - `live_conflicting_permanent_and_save_replay` for conflicting parameters set '403': - description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded + x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded + description: | + Disambiguate via `type`: + - `live_not_enabled` for a disabled live feature + - `live_not_allowing_replay` for a disabled replay feature + - `max_instance_lives_limit_reached` for the absolute concurrent live limit + - `max_user_lives_limit_reached` for the user concurrent live limit requestBody: content: multipart/form-data: @@ -2097,7 +2210,7 @@ paths: description: Enable or disable comments for this live video/replay type: boolean downloadEnabled: - description: Enable or disable downloading for the replay of this live + description: Enable or disable downloading for the replay of this live video type: boolean required: - channelId @@ -2239,7 +2352,7 @@ paths: type: string - name: videoIs in: query - description: only list blacklisted or deleted videos + description: only list deleted or blocklisted videos schema: type: string enum: @@ -2874,7 +2987,7 @@ paths: post: summary: Create a video playlist description: If the video playlist is set as public, `videoChannelId` is mandatory. - operationId: createPlaylist + operationId: addPlaylist security: - OAuth2: [] tags: @@ -2894,6 +3007,8 @@ paths: $ref: '#/components/schemas/VideoPlaylist/properties/id' uuid: $ref: '#/components/schemas/VideoPlaylist/properties/uuid' + shortUUID: + $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID' requestBody: content: multipart/form-data: @@ -2994,6 +3109,7 @@ paths: /video-playlists/{playlistId}/videos: get: summary: 'List videos of a playlist' + operationId: getVideoPlaylistVideos tags: - Videos - Video Playlists @@ -3008,6 +3124,7 @@ paths: $ref: '#/components/schemas/VideoListResponse' post: summary: Add a video in a playlist + operationId: addVideoPlaylistVideo security: - OAuth2: [] tags: @@ -3054,6 +3171,7 @@ paths: /video-playlists/{playlistId}/videos/reorder: post: summary: 'Reorder a playlist' + operationId: reorderVideoPlaylist security: - OAuth2: [] tags: @@ -3088,6 +3206,7 @@ paths: /video-playlists/{playlistId}/videos/{playlistElementId}: put: summary: Update a playlist element + operationId: putVideoPlaylistVideo security: - OAuth2: [] tags: @@ -3114,6 +3233,7 @@ paths: description: Stop the video at this specific timestamp delete: summary: Delete an element from a playlist + operationId: delVideoPlaylistVideo security: - OAuth2: [] tags: @@ -3368,6 +3488,7 @@ paths: tags: - Search summary: Search videos + operationId: searchVideos parameters: - name: search in: query @@ -3444,6 +3565,7 @@ paths: tags: - Search summary: Search channels + operationId: searchChannels parameters: - name: search in: query @@ -3471,6 +3593,47 @@ paths: '500': description: search index unavailable + /search/video-playlists: + get: + tags: + - Search + summary: Search playlists + operationId: searchPlaylists + parameters: + - name: search + in: query + required: true + description: > + String to search. If the user can make a remote URI search, and the string is an URI then the + PeerTube instance will fetch the remote object and add it to its database. Then, + you can use the REST API to fetch the complete playlist information and interact with it. + schema: + type: string + - $ref: '#/components/parameters/start' + - $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 + content: + application/json: + schema: + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/VideoPlaylist' + '500': + description: search index unavailable + /server/blocklist/accounts: get: tags: @@ -3632,6 +3795,7 @@ paths: tags: - Video Mirroring summary: List videos being mirrored + operationId: getMirroredVideos security: - OAuth2: - admin @@ -3661,6 +3825,7 @@ paths: tags: - Video Mirroring summary: Mirror a video + operationId: putMirroredVideo security: - OAuth2: - admin @@ -3689,6 +3854,7 @@ paths: tags: - Video Mirroring summary: Delete a mirror done on a video + operationId: delMirroredVideo security: - OAuth2: - admin @@ -3710,6 +3876,7 @@ paths: tags: - Feeds summary: List comments on videos + operationId: getSyndicatedComments parameters: - name: format in: path @@ -3804,6 +3971,7 @@ paths: tags: - Feeds summary: List videos + operationId: getSyndicatedVideos parameters: - name: format in: path @@ -3892,6 +4060,7 @@ paths: - Feeds - Account summary: List videos of subscriptions tied to a token + operationId: getSyndicatedSubscriptionVideos parameters: - name: format in: path @@ -3954,6 +4123,7 @@ paths: tags: - Plugins summary: List plugins + operationId: getPlugins security: - OAuth2: - admin @@ -3982,6 +4152,7 @@ paths: tags: - Plugins summary: List available plugins + operationId: getAvailablePlugins security: - OAuth2: - admin @@ -4016,6 +4187,7 @@ paths: tags: - Plugins summary: Install a plugin + operationId: addPlugin security: - OAuth2: - admin @@ -4050,6 +4222,7 @@ paths: tags: - Plugins summary: Update a plugin + operationId: updatePlugin security: - OAuth2: - admin @@ -4086,6 +4259,7 @@ paths: tags: - Plugins summary: Uninstall a plugin + operationId: uninstallPlugin security: - OAuth2: - admin @@ -4112,6 +4286,7 @@ paths: tags: - Plugins summary: Get a plugin + operationId: getPlugin security: - OAuth2: - admin @@ -4298,7 +4473,7 @@ components: name: sort in: query required: false - description: Sort blacklists by criteria + description: Sort blocklists by criteria schema: type: string enum: @@ -4374,11 +4549,12 @@ components: name: id in: path required: true - description: The object id or uuid + description: The object id, uuid or short uuid schema: oneOf: - $ref: '#/components/schemas/id' - $ref: '#/components/schemas/UUIDv4' + - $ref: '#/components/schemas/shortUUID' playlistId: name: playlistId in: path @@ -4436,7 +4612,7 @@ components: required: true description: The thread id (root comment id) schema: - $ref: '#/components/schemas/VideoCommentThreadTree/properties/comment/properties/id' + type: integer commentId: name: commentId in: path @@ -4643,6 +4819,10 @@ components: pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' minLength: 36 maxLength: 36 + shortUUID: + type: string + description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid + example: 2y84q2MQUMWPbiEcxNXMgC username: type: string description: immutable name of the user, used to find or mention its actor @@ -4761,7 +4941,7 @@ components: enum: - 0 - 1 - description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)' + description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)' example: 1 VideoStateConstant: @@ -4972,6 +5152,9 @@ components: description: universal identifier for the video, that can be used across instances allOf: - $ref: '#/components/schemas/UUIDv4' + shortUUID: + allOf: + - $ref: '#/components/schemas/shortUUID' isLive: type: boolean createdAt: @@ -5351,6 +5534,9 @@ components: $ref: '#/components/schemas/id' uuid: $ref: '#/components/schemas/UUIDv4' + shortUUID: + allOf: + - $ref: '#/components/schemas/shortUUID' createdAt: type: string format: date-time @@ -5720,6 +5906,12 @@ components: indexUrl: type: string format: url + homepage: + type: object + properties: + enabled: + type: boolean + ServerConfigAbout: properties: instance: @@ -5910,6 +6102,12 @@ components: type: boolean manualApproval: type: boolean + + CustomHomepage: + properties: + content: + type: string + Follow: properties: id: @@ -6114,6 +6312,8 @@ components: $ref: '#/components/schemas/Video/properties/id' uuid: $ref: '#/components/schemas/Video/properties/uuid' + shortUUID: + $ref: '#/components/schemas/Video/properties/shortUUID' CommentThreadResponse: properties: total: @@ -6215,7 +6415,7 @@ components: # optionally present fields: they require WITH_STATS scope videosCount: type: integer - description: Count of videos published + description: Count of videos published abusesCount: type: integer description: Count of reports/abuses of which the user is a target