aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/api/openapi.yaml
diff options
context:
space:
mode:
Diffstat (limited to 'support/doc/api/openapi.yaml')
-rw-r--r--support/doc/api/openapi.yaml51
1 files changed, 35 insertions, 16 deletions
diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index d4fe15664..24a9eb9c2 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -12,8 +12,6 @@ info:
12 url: 'https://joinpeertube.org/img/brand.png' 12 url: 'https://joinpeertube.org/img/brand.png'
13 altText: PeerTube Project Homepage 13 altText: PeerTube Project Homepage
14 description: | 14 description: |
15 # Introduction
16
17 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite 15 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
18 HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with 16 HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
19 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO) 17 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
@@ -23,13 +21,14 @@ info:
23 - [Go](https://framagit.org/framasoft/peertube/clients/go) 21 - [Go](https://framagit.org/framasoft/peertube/clients/go)
24 - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin) 22 - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
25 23
26 See the [Quick Start guide](https://docs.joinpeertube.org/api-rest-getting-started) so you can play with the PeerTube API. 24 See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
25 examples of using with the PeerTube API.
27 26
28 # Authentication 27 # Authentication
29 28
30 When you sign up for an account, you are given the possibility to generate 29 When you sign up for an account on a PeerTube instance, you are given the possibility
31 sessions, and authenticate using this session token. One session token can 30 to generate sessions on it, and authenticate there using a session token. Only __one
32 currently be used at a time. 31 session token can currently be used at a time__.
33 32
34 ## Roles 33 ## Roles
35 34
@@ -48,6 +47,29 @@ info:
48 "error": "Token is invalid." // example exposed error message 47 "error": "Token is invalid." // example exposed error message
49 } 48 }
50 ``` 49 ```
50
51 # Rate limits
52
53 We are rate-limiting all endpoints of PeerTube's API. Here is how it is configured by default:
54
55 | Endpoint | Calls | Time frame |
56 |-------------------------|------------------|---------------------------|
57 | `/*` | 50 | 10 seconds |
58 | `POST /users/token` | 15 | 5 minutes |
59 | `POST /users/register` | 2¹ | 5 minutes |
60 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
61
62 Depending on the endpoint, ¹failed requests are not taken into account. A service
63 limit is announced by a `429 Too Many Requests` status code.
64
65 You can get details about how your rate limit is going by reading following headers:
66
67 | Header | Description |
68 |-------------------------|------------------------------------------------------------|
69 | X-RateLimit-Limit | Number of max requests allowed in the current time period |
70 | X-RateLimit-Remaining | Number of remaining requests in the current time period |
71 | X-RateLimit-Reset | Timestamp of end of current time period as UNIX timestamp |
72 | Retry-After | Seconds to delay after the first `429` is received |
51externalDocs: 73externalDocs:
52 url: https://docs.joinpeertube.org/api-rest-reference.html 74 url: https://docs.joinpeertube.org/api-rest-reference.html
53tags: 75tags:
@@ -3959,19 +3981,16 @@ components:
3959 - video-live-ending 3981 - video-live-ending
3960 securitySchemes: 3982 securitySchemes:
3961 OAuth2: 3983 OAuth2:
3962 description: > 3984 description: |
3963 In the header: *Authorization: Bearer <token\>*
3964
3965
3966 Authenticating via OAuth requires the following steps: 3985 Authenticating via OAuth requires the following steps:
3967 3986 - Have an activated account
3968
3969 - Have an account with sufficient authorization levels
3970
3971 - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a 3987 - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a
3972 Bearer Token 3988 Bearer Token for that account at `/api/v1/users/token`
3989 - Make authenticated requests, putting *Authorization: Bearer <token\>*
3990 - Profit, depending on the role assigned to the account
3973 3991
3974 - Make Authenticated Requests 3992 Note that the __access token is valid for 1 day__ and, and is given
3993 along with a __refresh token valid for 2 weeks__.
3975 type: oauth2 3994 type: oauth2
3976 flows: 3995 flows:
3977 password: 3996 password: