aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/api/openapi.yaml
diff options
context:
space:
mode:
authorRigel Kent <sendmemail@rigelk.eu>2021-06-01 01:36:53 +0200
committerChocobozzz <chocobozzz@cpy.re>2021-06-02 16:57:07 +0200
commit76148b27f7501bac061992136852be4303370c8d (patch)
treefc0559253e833c9252fa14ebaec5321d88bfb4e8 /support/doc/api/openapi.yaml
parent5ed25fb76e920dac364cb9ef46f14ec4bd372949 (diff)
downloadPeerTube-76148b27f7501bac061992136852be4303370c8d.tar.gz
PeerTube-76148b27f7501bac061992136852be4303370c8d.tar.zst
PeerTube-76148b27f7501bac061992136852be4303370c8d.zip
refactor API errors to standard error format
Diffstat (limited to 'support/doc/api/openapi.yaml')
-rw-r--r--support/doc/api/openapi.yaml35
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