diff options
| -rw-r--r-- | support/doc/api/openapi.yaml | 34 |
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: |