X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=8ad98a9a9a13933a510467e8ef552ef356490f32;hb=d8b34ee55b654912f86bb8b472d391ced8c28f64;hp=f3edca6824ce23d9845beb4a32632402e3ac3f69;hpb=2291a412d25bd139398ca9e7a5131d0c1e4ffd7d;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index f3edca682..8ad98a9a9 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: 2.3.0 + version: 3.0.1 contact: name: PeerTube Community url: 'https://joinpeertube.org' @@ -70,6 +70,9 @@ tags: description: > Operations related to your subscriptions to video channels, their new videos, and how to keep up to date with their latest publications! + - name: My History + description: > + Operations related to your watch history. - name: My Notifications description: > Notifications following new videos, follows or reports. They allow you @@ -150,6 +153,7 @@ x-tagGroups: - My User - My Subscriptions - My Notifications + - My History - name: Videos tags: - Video @@ -160,6 +164,7 @@ x-tagGroups: - Video Playlists - Video Ownership Change - Video Mirroring + - Live Videos - Feeds - name: Search tags: @@ -233,8 +238,8 @@ paths: }) - lang: Shell source: | - # pip install httpie - http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos + ## DEPENDENCIES: jq + curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq - lang: Ruby source: | require 'net/http' @@ -305,7 +310,7 @@ paths: - Config security: - OAuth2: - - admin + - admin responses: '200': description: successful operation @@ -319,7 +324,7 @@ paths: - Config security: - OAuth2: - - admin + - admin responses: '200': description: successful operation @@ -335,7 +340,7 @@ paths: - Config security: - OAuth2: - - admin + - admin responses: '200': description: successful operation @@ -344,22 +349,24 @@ paths: summary: List instance jobs security: - OAuth2: - - admin + - admin tags: - Job parameters: - name: state in: path required: true - description: The state of the job + description: The state of the job ('' for for no filter) schema: type: string enum: + - '' - active - completed - failed - waiting - delayed + - $ref: '#/components/parameters/jobType' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' @@ -454,7 +461,7 @@ paths: post: security: - OAuth2: - - admin + - admin tags: - Instance Follows summary: Follow a server @@ -480,7 +487,7 @@ paths: summary: Create a user security: - OAuth2: - - admin + - admin tags: - Users responses: @@ -544,7 +551,7 @@ paths: summary: Delete a user security: - OAuth2: - - admin + - admin tags: - Users operationId: delUserId @@ -633,7 +640,7 @@ paths: summary: Get video imports of my user security: - OAuth2: - - user + - user tags: - Videos - My User @@ -710,7 +717,7 @@ paths: summary: Get my user subscriptions security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -726,7 +733,7 @@ paths: summary: Add subscription to my user security: - OAuth2: - - user + - user requestBody: content: application/json: @@ -751,7 +758,7 @@ paths: summary: Get if subscriptions exist for my user security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -796,7 +803,7 @@ paths: summary: Get subscription of my user security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -812,7 +819,7 @@ paths: summary: Delete subscription of my user security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -916,6 +923,44 @@ paths: responses: '204': description: successful operation + /users/me/history/videos: + get: + summary: List watched videos history + security: + - OAuth2: [] + tags: + - My History + parameters: + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/search' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoListResponse' + /users/me/history/videos/remove: + post: + summary: Clear video history + security: + - OAuth2: [] + tags: + - My History + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + beforeDate: + description: history before this date will be deleted + type: string + format: date-time + responses: + '204': + description: successful operation /users/me/avatar/pick: post: summary: Update my user avatar @@ -930,6 +975,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Avatar' + '413': + description: image file too large + headers: + X-File-Maximum-Size: + schema: + type: string + format: Nginx size + description: Maximum file size for the avatar requestBody: content: multipart/form-data: @@ -1262,12 +1315,24 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' + '400': + description: invalid file field, schedule date or parameter '403': - description: user video quota is exceeded with this video + 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 + headers: + X-File-Maximum-Size: + schema: + type: string + format: Nginx size + description: Maximum file size for the video + '415': + description: video type unsupported '422': - description: invalid input file + description: video unreadable requestBody: content: multipart/form-data: @@ -1307,7 +1372,7 @@ paths: type: string waitTranscoding: description: Whether or not we wait transcoding before publish the video - type: string + type: boolean support: description: A text tell the audience how to support the video creator example: Please support my work on ! <3 @@ -1331,6 +1396,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 @@ -1351,8 +1419,7 @@ paths: x-code-samples: - lang: Shell source: | - ## DEPENDENCIES: httpie, jq - # pip install httpie + ## DEPENDENCIES: jq USERNAME="" PASSWORD="" FILE_PATH="" @@ -1361,19 +1428,23 @@ paths: API_PATH="https://peertube2.cpy.re/api/v1" ## AUTH - client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id") - client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret") - token=$(http -b --form POST "$API_PATH/users/token" \ - client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \ - username=$USERNAME \ - password=$PASSWORD \ + client_id=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_id") + client_secret=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_secret") + token=$(curl -s "$API_PATH/users/token" \ + --data client_id="$client_id" \ + --data client_secret="$client_secret" \ + --data grant_type=password \ + --data response_type=code \ + --data username="$USERNAME" \ + --data password="$PASSWORD" \ | jq -r ".access_token") ## VIDEO UPLOAD - http -b --form POST "$API_PATH/videos/upload" \ - videofile@$FILE_PATH \ - channelId=$CHANNEL_ID \ - name=$NAME \ - "Authorization:Bearer $token" + curl -s "$API_PATH/videos/upload" \ + -H "Authorization: Bearer $token" \ + --max-time 600 \ + --form videofile=@"$FILE_PATH" \ + --form channelId=$CHANNEL_ID \ + --form name="$NAME" /videos/imports: post: summary: Import a video @@ -1425,14 +1496,14 @@ paths: type: string waitTranscoding: description: Whether or not we wait transcoding before publish the video - type: string + 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: string + type: boolean name: description: Video name type: string @@ -1447,7 +1518,10 @@ paths: maxLength: 30 commentsEnabled: description: Enable or disable comments for this video - type: string + type: boolean + downloadEnabled: + description: Enable or disable downloading for this video + type: boolean scheduleUpdate: $ref: '#/components/schemas/VideoScheduledUpdate' required: @@ -1467,10 +1541,170 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' + '400': + description: '`magnetUri` or `targetUrl` or a torrent file missing' + '403': + description: video didn't pass pre-import filter '409': description: HTTP or Torrent/magnetURI import not enabled + + /videos/live: + post: + summary: Create a live + security: + - OAuth2: [] + tags: + - Live Videos + - Video + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoUploadResponse' + '403': + description: Live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + channelId: + description: Channel id that will contain this live video + type: integer + saveReplay: + type: boolean + permanentLive: + description: User can stream multiple times in a permanent live + type: boolean + thumbnailfile: + description: Live video/replay thumbnail file + type: string + format: binary + previewfile: + description: Live video/replay preview file + type: string + format: binary + privacy: + $ref: '#/components/schemas/VideoPrivacySet' + category: + description: Live video/replay category + type: string + licence: + description: Live video/replay licence + type: string + language: + description: Live video/replay language + type: string + description: + description: Live video/replay description + type: string + support: + description: A text tell the audience how to support the creator + example: Please support my work on ! <3 + type: string + nsfw: + description: Whether or not this live video/replay contains sensitive content + type: boolean + name: + description: Live video/replay name + type: string + tags: + description: Live video/replay 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 live video/replay + type: boolean + downloadEnabled: + description: Enable or disable downloading for the replay of this live + type: boolean + required: + - channelId + - name + encoding: + thumbnailfile: + contentType: image/jpeg + previewfile: + contentType: image/jpeg + + /videos/live/{id}: + get: + summary: Get a live information + security: + - OAuth2: [] + tags: + - Live Videos + - Video + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/LiveVideoResponse' + put: + summary: Update a live information + security: + - OAuth2: [] + tags: + - Live Videos + - Video + parameters: + - $ref: '#/components/parameters/idOrUUID' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LiveVideoUpdate' + responses: + '204': + description: Successful operation '400': - description: '`magnetUri` or `targetUrl` or a torrent file missing' + description: Bad parameters or trying to update a live that has already started + '403': + description: Trying to save replay of the live but saving replay is not enabled on the instance + + /users/me/abuses: + get: + summary: List my abuses + security: + - OAuth2: [] + tags: + - Abuses + - My User + parameters: + - name: id + in: query + description: only list the report with this id + schema: + type: integer + - name: state + in: query + schema: + $ref: '#/components/schemas/AbuseStateSet' + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/abusesSort' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Abuse' + /abuses: get: summary: List abuses @@ -1498,13 +1732,8 @@ paths: type: string - name: state in: query - description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)' schema: - type: integer - enum: - - 1 - - 2 - - 3 + $ref: '#/components/schemas/AbuseStateSet' - name: searchReporter in: query description: only list reports of a specific reporter @@ -1553,7 +1782,7 @@ paths: schema: type: array items: - $ref: '#/components/schemas/VideoAbuse' + $ref: '#/components/schemas/Abuse' post: summary: Report an abuse @@ -1641,8 +1870,8 @@ paths: summary: Delete an abuse security: - OAuth2: - - admin - - moderator + - admin + - moderator parameters: - $ref: '#/components/parameters/abuseId' responses: @@ -1650,14 +1879,71 @@ paths: description: successful operation '404': description: block not found + '/abuses/{abuseId}/messages': + get: + summary: List messages of an abuse + security: + - OAuth2: [] + tags: + - Abuses + parameters: + - $ref: '#/components/parameters/abuseId' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AbuseMessage' + + post: + summary: Add message to an abuse + security: + - OAuth2: [] + tags: + - Abuses + parameters: + - $ref: '#/components/parameters/abuseId' + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + message: + description: Message to send + type: string + required: + - message + responses: + '200': + description: successful operation + '400': + description: incorrect request parameters + '/abuses/{abuseId}/messages/{abuseMessageId}': + delete: + summary: Delete an abuse message + security: + - OAuth2: [] + tags: + - Abuses + parameters: + - $ref: '#/components/parameters/abuseId' + - $ref: '#/components/parameters/abuseMessageId' + responses: + '204': + description: successful operation '/videos/{id}/blacklist': post: summary: Block a video security: - OAuth2: - - admin - - moderator + - admin + - moderator tags: - Video Blocks parameters: @@ -1669,8 +1955,8 @@ paths: summary: Unblock a video by its id security: - OAuth2: - - admin - - moderator + - admin + - moderator tags: - Video Blocks parameters: @@ -1687,8 +1973,8 @@ paths: summary: List video blocks security: - OAuth2: - - admin - - moderator + - admin + - moderator parameters: - name: type in: query @@ -1751,6 +2037,9 @@ paths: /videos/{id}/captions/{captionLanguage}: put: summary: Add or replace a video caption + security: + - OAuth2: + - user tags: - Video Captions parameters: @@ -1776,6 +2065,9 @@ paths: description: video or language not found delete: summary: Delete a video caption + security: + - OAuth2: + - user tags: - Video Captions parameters: @@ -3289,7 +3581,7 @@ components: name: name in: path required: true - description: The name of the account + description: The username or handle of the account schema: type: string example: chocobozzz | chocobozzz@example.org @@ -3329,6 +3621,13 @@ components: description: Abuse id schema: type: integer + abuseMessageId: + name: abuseMessageId + in: path + required: true + description: Abuse message id + schema: + type: integer captionLanguage: name: captionLanguage in: path @@ -3457,9 +3756,10 @@ components: in: query required: false description: > - Special filters (local for instance) which might require special rights: + Special filters which might require special rights: * `local` - only videos local to the instance * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges) + * `all` - all videos, showing private and unlisted videos (requires Admin privileges) schema: type: string enum: @@ -3483,6 +3783,26 @@ components: schema: type: string example: peertube-plugin-auth-ldap + jobType: + name: jobType + in: query + required: false + description: job type + schema: + type: string + enum: + - activitypub-follow + - activitypub-http-broadcast + - activitypub-http-fetcher + - activitypub-http-unicast + - email + - video-transcoding + - video-file-import + - video-import + - videos-views + - activitypub-refresher + - video-redundancy + - video-live-ending securitySchemes: OAuth2: description: > @@ -3596,7 +3916,7 @@ components: - 1 - 2 - 3 - description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)' + description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)' AbuseStateConstant: properties: id: @@ -3622,7 +3942,7 @@ components: properties: id: type: integer - description: 'Video resolution (240, 360, 720 ...)' + description: 'Video resolution (240, 360, 720, 1080, 1440 or 2160)' example: 240 label: type: string @@ -3728,6 +4048,7 @@ components: format: url files: type: array + description: 'Video files associated to this playlist. The difference with the root "files" property is that these files are fragmented, so they can be used in this streaming playlist (HLS etc)' items: $ref: '#/components/schemas/VideoFile' redundancies: @@ -3757,6 +4078,8 @@ components: type: string format: uuid example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + isLive: + type: boolean createdAt: type: string format: date-time @@ -3792,7 +4115,7 @@ components: example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg previewPath: type: string - example: /static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg + example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg embedPath: type: string example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee @@ -3854,6 +4177,7 @@ components: example: [flowers, gardening] files: type: array + description: 'WebTorrent/raw video files. Can be empty if WebTorrent is disabled on the server. In this case, video files will be in the "streamingPlaylists[].files" property' items: $ref: '#/components/schemas/VideoFile' commentsEnabled: @@ -3957,7 +4281,7 @@ components: format: date-time video: $ref: '#/components/schemas/Video' - VideoAbuse: + Abuse: properties: id: type: integer @@ -3988,6 +4312,19 @@ components: createdAt: type: string format: date-time + AbuseMessage: + properties: + id: + type: integer + message: + type: string + byModerator: + type: boolean + createdAt: + type: string + format: date-time + account: + $ref: '#/components/schemas/AccountSummary' VideoBlacklist: properties: id: @@ -4493,6 +4830,8 @@ components: type: boolean 1080p: type: boolean + 1440p: + type: boolean 2160p: type: boolean hls: @@ -4867,7 +5206,7 @@ components: properties: name: type: string - description: The name for the default channel + description: The username for the default channel pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/' displayName: type: string @@ -5304,9 +5643,31 @@ components: maxItems: 100 items: $ref: '#/components/schemas/Plugin' + + LiveVideoUpdate: + properties: + saveReplay: + type: boolean + permanentLive: + description: User can stream multiple times in a permanent live + type: boolean + + LiveVideoResponse: + properties: + rtmpUrl: + type: string + streamKey: + type: string + description: RTMP stream key to use to stream into this live video + saveReplay: + type: boolean + permanentLive: + description: User can stream multiple times in a permanent live + type: boolean + callbacks: searchIndex: - '{%CONFIG.SEARCH.SEARCH_INDEX.URL%}/api/v1/search/videos/': + 'https://search.example.org/api/v1/search/videos': post: summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget` responses: