From 2963c3432f3967675530162b1bf87b549cc124f5 Mon Sep 17 00:00:00 2001 From: Rigel Kent Date: Tue, 13 Nov 2018 23:27:58 +0100 Subject: updated REST API documentation --- support/doc/api/openapi.yaml | 168 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 155 insertions(+), 13 deletions(-) (limited to 'support/doc/api/openapi.yaml') diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index f3520a7b1..e88c05333 100644 --- a/support/doc/api/openapi.yaml +++ b/support/doc/api/openapi.yaml @@ -2,24 +2,105 @@ swagger: '2.0' info: title: PeerTube version: 1.1.0-alpha.2 - description: Federated (ActivityPub) video streaming platform using P2P (BitTorrent) directly in the web browser with WebTorrent and Angular. -host: peertube.example.com + contact: + name: PeerTube Community + url: 'https://joinpeertube.org' + license: + name: AGPLv3.0 + url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE' + x-logo: + url: 'https://joinpeertube.org/img/brand.png' + description: | + # Introduction + The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable + resource URLs. It returns HTTP response codes to indicate errors. It also + accepts and returns JSON in the HTTP body. You can use your favorite + HTTP/REST library for your programming language to use PeerTube. No official + SDK is currently provided. + + # Authentication + When you sign up for an account, you are given the possibility to generate + sessions, and authenticate using this session token. One session token can + currently be used at a time. securityDefinitions: OAuth2: - description: 'In the header: *Authorization: Bearer mytoken*' + description: | + In the header: *Authorization: Bearer * + + Authenticating via OAuth requires the following steps: + + - Have an account with sufficient authorization levels + - [Generate](https://docs.joinpeertube.org/lang/en/devdocs/rest.html) a Bearer Token + - Make Authenticated Requests type: oauth2 flow: password # Not implemented yet # authorizationUrl: https://example.com/oauth/authorize tokenUrl: https://peertube.example.com/api/v1/users/token + scopes: + admin: Admin scope + moderator: Moderator scope + user: User scope basePath: '/api/v1' schemes: - https +host: peertube.example.com +x-servers: + - url: 'https://peertube.cpy.re/api/v1' + description: Live Server +produces: + - application/json; charset=utf-8 +consumes: + - application/json +tags: + - name: Accounts + description: | + Using some features of PeerTube require authentication, for which Accounts + provide different levels of permission as well as associated user information. + Accounts also encompass remote accounts discovered across the federation. + - name: Config + description: | + Each server exposes public information regarding supported videos and options. + - name: Feeds + description: | + Feeds of videos and feeds of comments allow to see updates and get them in + an aggregator or script of your choice. + - name: Job + description: | + Jobs are long-running tasks enqueued and processed by the instance itself. + No additional worker registration is currently available. + - name: ServerFollowing + description: | + Managing servers which the instance interacts with is crucial to the concept + of federation in PeerTube and external video indexation. The PeerTube server + then deals with inter-server ActivityPub operations and propagates + information across its social graph by posting activities to actors' inbox + endpoints. + - name: VideoAbuse + description: | + Video abuses deal with reports of local or remote videos alike. + - name: Video + description: | + Operations dealing with listing, uploading, fetching or modifying videos. + - name: Search + description: | + The search helps to find _videos_ from within the instance and beyond. + Videos from other instances federated by the instance (that is, instances + followed by the instance) can be found via keywords and other criteria of + the advanced search. + - name: VideoComment + description: | + Operations dealing with comments to a video. Comments are organized in threads. + - name: VideoChannel + description: | + Operations dealing with creation, modification and video listing of a user's + channels. paths: '/accounts/{name}': get: tags: - Accounts + summary: Get the account by name consumes: - application/json produces: @@ -38,6 +119,8 @@ paths: get: tags: - Accounts + - Video + summary: Get videos for an account, provided the name of that account consumes: - application/json produces: @@ -49,14 +132,24 @@ paths: description: successful operation schema: $ref: '#/definitions/Video' + x-code-samples: + - lang: JavaScript + source: | + fetch('https://peertube.cpy.re/api/v1/accounts/{name}/videos') + .then(function(response) { + return response.json() + }).then(function(data) { + console.log(data) + }) /accounts: get: tags: - Accounts + summary: Get all accounts consumes: - application/json produces: - - application/json + - application/jsonhttps://peertube.cpy.re/api/v1 responses: '200': description: successful operation @@ -68,6 +161,7 @@ paths: get: tags: - Config + summary: Get the configuration of the server consumes: - application/json produces: @@ -79,6 +173,7 @@ paths: $ref: '#/definitions/ServerConfig' /feeds/videos.{format}: get: + summary: Get the feed of videos for the server, with optional filter by account name or id tags: - Feeds produces: @@ -108,8 +203,9 @@ paths: description: successful operation /jobs: get: + summary: Get list of jobs security: - - OAuth2: [ ] + - OAuth2: [ admin ] tags: - Job consumes: @@ -135,9 +231,10 @@ paths: '/server/following/{host}': delete: security: - - OAuth2: [ ] + - OAuth2: [ admin ] tags: - ServerFollowing + summary: Unfollow a server by hostname consumes: - application/json produces: @@ -155,6 +252,7 @@ paths: get: tags: - ServerFollowing + summary: Get followers of the server consumes: - application/json produces: @@ -174,6 +272,7 @@ paths: get: tags: - ServerFollowing + summary: Get servers followed by the server consumes: - application/json produces: @@ -191,9 +290,10 @@ paths: $ref: '#/definitions/Follow' post: security: - - OAuth2: [ ] + - OAuth2: [ admin ] tags: - ServerFollowing + summary: Follow a server consumes: - application/json produces: @@ -208,8 +308,9 @@ paths: $ref: "commons.yaml#/responses/emptySuccess" /users: post: + summary: Creates user security: - - OAuth2: [ ] + - OAuth2: [ admin ] tags: - User consumes: @@ -229,6 +330,7 @@ paths: schema: $ref: '#/definitions/AddUserResponse' get: + summary: Get a list of users security: - OAuth2: [ ] tags: @@ -250,8 +352,9 @@ paths: $ref: '#/definitions/User' '/users/{id}': delete: + summary: Delete a user by its id security: - - OAuth2: [ ] + - OAuth2: [ admin ] tags: - User consumes: @@ -264,6 +367,7 @@ paths: '204': $ref: "commons.yaml#/responses/emptySuccess" get: + summary: Get user by its id security: - OAuth2: [ ] tags: @@ -280,6 +384,7 @@ paths: schema: $ref: '#/definitions/User' put: + summary: Update user profile by its id security: - OAuth2: [ ] tags: @@ -300,6 +405,7 @@ paths: $ref: "commons.yaml#/responses/emptySuccess" /users/me: get: + summary: Get current user information security: - OAuth2: [ ] tags: @@ -316,6 +422,7 @@ paths: items: $ref: '#/definitions/User' put: + summary: Update current user information security: - OAuth2: [ ] tags: @@ -335,6 +442,7 @@ paths: $ref: "commons.yaml#/responses/emptySuccess" /users/me/video-quota-used: get: + summary: Get current user used quota security: - OAuth2: [ ] tags: @@ -351,6 +459,7 @@ paths: type: number '/users/me/videos/{videoId}/rating': get: + summary: Get rating of video by its id, among those of the current user security: - OAuth2: [ ] tags: @@ -372,6 +481,7 @@ paths: $ref: '#/definitions/GetMeVideoRating' /users/me/videos: get: + summary: Get videos of the current user security: - OAuth2: [ ] tags: @@ -393,6 +503,7 @@ paths: $ref: '#/definitions/Video' /users/register: post: + summary: Register a user tags: - User consumes: @@ -410,6 +521,7 @@ paths: $ref: "commons.yaml#/responses/emptySuccess" /users/me/avatar/pick: post: + summary: Update current user avatar security: - OAuth2: [ ] tags: @@ -430,6 +542,7 @@ paths: $ref: '#/definitions/Avatar' /videos: get: + summary: Get list of videos tags: - Video consumes: @@ -454,6 +567,7 @@ paths: $ref: '#/definitions/Video' /videos/categories: get: + summary: Get list of video licences known by the server tags: - Video consumes: @@ -469,6 +583,7 @@ paths: type: string /videos/licences: get: + summary: Get list of video licences known by the server tags: - Video consumes: @@ -484,6 +599,7 @@ paths: type: string /videos/languages: get: + summary: Get list of languages known by the server tags: - Video consumes: @@ -499,6 +615,7 @@ paths: type: string /videos/privacies: get: + summary: Get list of privacy policies supported by the server tags: - Video consumes: @@ -514,6 +631,7 @@ paths: type: string "/videos/{id}": put: + summary: Update metadata for a video by its id security: - OAuth2: [ ] tags: @@ -544,6 +662,7 @@ paths: schema: $ref: '#/definitions/Video' get: + summary: Get a video by its id tags: - Video consumes: @@ -558,6 +677,7 @@ paths: schema: $ref: '#/definitions/Video' delete: + summary: Delete a video by its id security: - OAuth2: [ ] tags: @@ -573,6 +693,7 @@ paths: $ref: "commons.yaml#/responses/emptySuccess" "/videos/{id}/description": get: + summary: Get a video description by its id tags: - Video consumes: @@ -588,6 +709,7 @@ paths: type: string "/videos/{id}/views": post: + summary: Add a view to the video by its id tags: - Video consumes: @@ -601,6 +723,7 @@ paths: $ref: "commons.yaml#/responses/emptySuccess" /videos/upload: post: + summary: Upload a video file with its metadata security: - OAuth2: [ ] tags: @@ -641,6 +764,7 @@ paths: $ref: '#/definitions/VideoUploadResponse' /videos/abuse: get: + summary: Get list of reported video abuses security: - OAuth2: [ ] tags: @@ -662,6 +786,7 @@ paths: $ref: '#/definitions/VideoAbuse' "/videos/{id}/abuse": post: + summary: Report an abuse, on a video by its id security: - OAuth2: [ ] tags: @@ -677,8 +802,9 @@ paths: $ref: "commons.yaml#/responses/emptySuccess" "/videos/{id}/blacklist": post: + summary: Put on blacklist a video by its id security: - - OAuth2: [ ] + - OAuth2: [ admin, moderator ] tags: - VideoBlacklist consumes: @@ -691,8 +817,9 @@ paths: '204': $ref: "commons.yaml#/responses/emptySuccess" delete: + summary: Delete an entry of the blacklist of a video by its id security: - - OAuth2: [ ] + - OAuth2: [ admin, moderator ] tags: - VideoBlacklist consumes: @@ -706,8 +833,9 @@ paths: $ref: "commons.yaml#/responses/emptySuccess" /videos/blacklist: get: + summary: Get list of videos on blacklist security: - - OAuth2: [ ] + - OAuth2: [ admin, moderator ] tags: - VideoBlacklist consumes: @@ -727,6 +855,7 @@ paths: $ref: '#/definitions/VideoBlacklist' /video-channels: get: + summary: Get list of video channels tags: - VideoChannel consumes: @@ -745,6 +874,7 @@ paths: items: $ref: '#/definitions/VideoChannel' post: + summary: Creates a video channel for the current user security: - OAuth2: [ ] tags: @@ -763,6 +893,7 @@ paths: $ref: "commons.yaml#/responses/emptySuccess" "/video-channels/{id}": get: + summary: Get a video channel by its id tags: - VideoChannel consumes: @@ -777,6 +908,7 @@ paths: schema: $ref: '#/definitions/VideoChannel' put: + summary: Update a video channel by its id security: - OAuth2: [ ] tags: @@ -795,6 +927,7 @@ paths: '204': $ref: "commons.yaml#/responses/emptySuccess" delete: + summary: Delete a video channel by its id security: - OAuth2: [ ] tags: @@ -810,6 +943,7 @@ paths: $ref: "commons.yaml#/responses/emptySuccess" "/video-channels/{id}/videos": get: + summary: Get videos of a video channel by its id tags: - VideoChannel consumes: @@ -825,6 +959,7 @@ paths: $ref: '#/definitions/Video' /accounts/{name}/video-channels: get: + summary: Get video channels of an account by its name tags: - VideoChannel consumes: @@ -842,6 +977,7 @@ paths: $ref: '#/definitions/VideoChannel' "/videos/{id}/comment-threads": get: + summary: Get the comment threads of a video by its id tags: - VideoComment consumes: @@ -859,6 +995,7 @@ paths: schema: $ref: '#/definitions/CommentThreadResponse' post: + summary: Creates a comment thread, on a video by its id security: - OAuth2: [ ] tags: @@ -876,6 +1013,7 @@ paths: $ref: '#/definitions/CommentThreadPostResponse' "/videos/{id}/comment-threads/{threadId}": get: + summary: Get the comment thread by its id, of a video by its id tags: - VideoComment consumes: @@ -892,6 +1030,7 @@ paths: $ref: '#/definitions/VideoCommentThreadTree' "/videos/{id}/comments/{commentId}": post: + summary: Creates a comment in a comment thread by its id, of a video by its id security: - OAuth2: [ ] tags: @@ -909,6 +1048,7 @@ paths: schema: $ref: '#/definitions/CommentThreadPostResponse' delete: + summary: Delete a comment in a comment therad by its id, of a video by its id security: - OAuth2: [ ] tags: @@ -925,6 +1065,7 @@ paths: $ref: "commons.yaml#/responses/emptySuccess" "/videos/{id}/rate": put: + summary: Vote for a video by its id security: - OAuth2: [ ] tags: @@ -942,6 +1083,7 @@ paths: get: tags: - Search + summary: Get the videos corresponding to a given query consumes: - application/json produces: @@ -1383,4 +1525,4 @@ definitions: name: type: string description: - type: string \ No newline at end of file + type: string -- cgit v1.2.3