diff options
Diffstat (limited to 'support/doc/api')
| -rw-r--r-- | support/doc/api/openapi.yaml | 35 |
1 files changed, 21 insertions, 14 deletions
diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 34bf9c411..52a834056 100644 --- a/support/doc/api/openapi.yaml +++ b/support/doc/api/openapi.yaml | |||
| @@ -38,46 +38,53 @@ 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. | 41 | of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body. |
| 42 | 42 | ||
| 43 | ``` | 43 | ``` |
| 44 | HTTP 1.1 404 Not Found | 44 | HTTP 1.1 404 Not Found |
| 45 | Content-Type: application/json | 45 | Content-Type: application/problem+json; charset=utf-8 |
| 46 | 46 | ||
| 47 | { | 47 | { |
| 48 | "errorCode": 1 | 48 | "detail": "Video not found", |
| 49 | "error": "Account not found" | 49 | "status": 404, |
| 50 | "title": "Not Found", | ||
| 51 | "type": "about:blank" | ||
| 50 | } | 52 | } |
| 51 | ``` | 53 | ``` |
| 52 | 54 | ||
| 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), | 55 | We provide error types 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. | 56 | but it is still optional. |
| 55 | 57 | ||
| 56 | ### Validation errors | 58 | ### Validation errors |
| 57 | 59 | ||
| 58 | Each parameter is evaluated on its own against a set of rules before the route validator | 60 | 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 | 61 | proceeds with potential testing involving parameter combinations. Errors coming from validation |
| 60 | errors appear earlier and benefit from a more detailed error type: | 62 | errors appear earlier and benefit from a more detailed error type: |
| 61 | 63 | ||
| 62 | ``` | 64 | ``` |
| 63 | HTTP 1.1 400 Bad Request | 65 | HTTP 1.1 400 Bad Request |
| 64 | Content-Type: application/json | 66 | Content-Type: application/problem+json; charset=utf-8 |
| 65 | 67 | ||
| 66 | { | 68 | { |
| 67 | "errors": { | 69 | "detail": "Incorrect request parameters: id", |
| 70 | "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180", | ||
| 71 | "invalid-params": { | ||
| 68 | "id": { | 72 | "id": { |
| 69 | "value": "a117eb-c6a9-4756-bb09-2a956239f", | 73 | "location": "params", |
| 70 | "msg": "Should have a valid id", | 74 | "msg": "Invalid value", |
| 71 | "param": "id", | 75 | "param": "id", |
| 72 | "location": "params" | 76 | "value": "9c9de5e8-0a1e-484a-b099-e80766180" |
| 73 | } | 77 | } |
| 74 | } | 78 | }, |
| 79 | "status": 400, | ||
| 80 | "title": "Bad Request", | ||
| 81 | "type": "about:blank" | ||
| 75 | } | 82 | } |
| 76 | ``` | 83 | ``` |
| 77 | 84 | ||
| 78 | Where `id` is the name of the field concerned by the error, within the route definition. | 85 | 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 | 86 | `invalid-params.<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` | 87 | `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg` |
| 81 | is about. | 88 | is about. |
| 82 | 89 | ||
| 83 | # Rate limits | 90 | # Rate limits |