X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=b43b6bfa0fdb480da68b8c3c3bba7b4985e75027;hb=c756bae079e02873f6433582ca14a092fec0db27;hp=0762e590ada0f35a9f3abba6509515f7576fffe1;hpb=1c5e49e75284100b7b1fc8b4e73c8ba53fe22e89;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 0762e590a..b43b6bfa0 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 + version: 3.2.1 contact: name: PeerTube Community url: https://joinpeertube.org @@ -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: @@ -923,6 +954,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: | @@ -1759,6 +1802,7 @@ paths: '/videos/{id}/views': post: summary: Add a view to a video + operationId: addView tags: - Video parameters: @@ -1770,6 +1814,7 @@ paths: '/videos/{id}/watching': put: summary: Set watching progress of a video + operationId: setProgress tags: - Video security: @@ -1803,14 +1848,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: @@ -1909,10 +1955,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: @@ -1988,10 +2036,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 @@ -2024,6 +2076,8 @@ paths: schema: type: number example: 0 + '404': + description: upload not found /videos/imports: post: @@ -2077,8 +2131,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: @@ -2279,7 +2345,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: @@ -4357,7 +4423,7 @@ components: name: sort in: query required: false - description: Sort blacklists by criteria + description: Sort blocklists by criteria schema: type: string enum: @@ -4820,7 +4886,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: