aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/api
diff options
context:
space:
mode:
authorRigel Kent <sendmemail@rigelk.eu>2021-05-13 14:10:04 +0200
committerRigel Kent <sendmemail@rigelk.eu>2021-05-13 14:10:11 +0200
commitb036eb057efda11259400d3d204c1e48c9755de8 (patch)
tree8aceddbec83d8c7a27e1f48063c1c26fa4fc6168 /support/doc/api
parente2464d22a5f19168022e72c77e82019726216542 (diff)
downloadPeerTube-b036eb057efda11259400d3d204c1e48c9755de8.tar.gz
PeerTube-b036eb057efda11259400d3d204c1e48c9755de8.tar.zst
PeerTube-b036eb057efda11259400d3d204c1e48c9755de8.zip
more faithful error description in openapi spec
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: