X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=76e78fe53a65fc12f4b51a754a18c76ed0de97d4;hb=171efc48e67498406feb6d7873b3482b41505515;hp=6c5a150870556d45ca98ccb95311fa70483ec936;hpb=a31e9b183ecfa9fe7abfae46750e454aa6ba244f;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 6c5a15087..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.1 + version: 3.3.0 contact: name: PeerTube Community url: https://joinpeertube.org @@ -716,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 @@ -734,28 +734,32 @@ 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: @@ -1740,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 @@ -1802,6 +1809,7 @@ paths: '/videos/{id}/views': post: summary: Add a view to a video + operationId: addView tags: - Video parameters: @@ -1813,6 +1821,7 @@ paths: '/videos/{id}/watching': put: summary: Set watching progress of a video + operationId: setProgress tags: - Video security: @@ -1851,7 +1860,10 @@ paths: '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: @@ -1951,7 +1963,11 @@ paths: type: number example: 0 '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: @@ -2027,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 @@ -2063,6 +2083,8 @@ paths: schema: type: number example: 0 + '404': + description: upload not found /videos/imports: post: @@ -2116,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: @@ -2176,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 @@ -2318,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: @@ -2973,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: @@ -3557,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: @@ -4396,7 +4473,7 @@ components: name: sort in: query required: false - description: Sort blacklists by criteria + description: Sort blocklists by criteria schema: type: string enum: @@ -4472,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 @@ -4741,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 @@ -4859,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: @@ -5070,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: @@ -5449,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 @@ -6224,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: