aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/api
diff options
context:
space:
mode:
Diffstat (limited to 'support/doc/api')
-rw-r--r--support/doc/api/openapi.yaml34
1 files changed, 26 insertions, 8 deletions
diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index f54df1dd0..6e82864a0 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -38,30 +38,48 @@ info:
38 # Errors 38 # Errors
39 39
40 The API uses standard HTTP status codes to indicate the success or failure 40 The API uses standard HTTP status codes to indicate the success or failure
41 of the API call. The body of the response will be JSON in the following 41 of the API call.
42 formats.
43 42
44 ``` 43 ```
44 HTTP 1.1 404 Not Found
45 Content-Type: application/json
46
45 { 47 {
46 "error": "Account not found" // error debug message 48 "errorCode": 1
49 "error": "Account not found"
47 } 50 }
48 ``` 51 ```
49 52
50 Validation errors benefit from a more detailed error type and return the HTTP `400 Bad Request` status code. 53 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),
54 but it is still optional.
55
56 ### Validation errors
57
58 Each parameter is evaluated on its own against a set of rules before the route validator
59 proceeds with potential testing involving parameter combinations. Errors coming from Validation
60 errors appear earlier and benefit from a more detailed error type:
51 61
52 ``` 62 ```
63 HTTP 1.1 400 Bad Request
64 Content-Type: application/json
65
53 { 66 {
54 "errors": { 67 "errors": {
55 "id": { // where 'id' is the name of the parameter concerned by the error. 68 "id": { //
56 "value": "a117eb-c6a9-4756-bb09-2a956239f", // value that triggered the error. 69 "value": "a117eb-c6a9-4756-bb09-2a956239f",
57 "msg": "Should have an valid id", // error debug message 70 "msg": "Should have a valid id",
58 "param": "id", 71 "param": "id",
59 "location": "params" // 'params', 'body', 'header', 'query' or 'cookies' 72 "location": "params"
60 } 73 }
61 } 74 }
62 } 75 }
63 ``` 76 ```
64 77
78 Where `id` is the name of the field concerned by the error, within the route definition.
79 `errors.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
80 `errors.<field>.value` reports the value that didn't pass validation whose `errors.<field>.msg`
81 is about.
82
65 # Rate limits 83 # Rate limits
66 84
67 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators: 85 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators: