aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc
diff options
context:
space:
mode:
Diffstat (limited to 'support/doc')
-rw-r--r--support/doc/api/openapi.yaml38
1 files changed, 31 insertions, 7 deletions
diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 9f40d74c6..ae4855878 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -53,14 +53,30 @@ info:
53 } 53 }
54 ``` 54 ```
55 55
56 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), 56 We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
57 but it is still optional. 57 but it is still optional. Types are used to disambiguate errors that bear the same status code
58 and are non-obvious:
59
60 ```
61 HTTP 1.1 403 Forbidden
62 Content-Type: application/problem+json; charset=utf-8
63
64 {
65 "detail": "Cannot get this video regarding follow constraints",
66 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
67 "status": 403,
68 "title": "Forbidden",
69 "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
70 }
71 ```
72
73 Here a 403 error could otherwise mean that the video is private or blocklisted.
58 74
59 ### Validation errors 75 ### Validation errors
60 76
61 Each parameter is evaluated on its own against a set of rules before the route validator 77 Each parameter is evaluated on its own against a set of rules before the route validator
62 proceeds with potential testing involving parameter combinations. Errors coming from validation 78 proceeds with potential testing involving parameter combinations. Errors coming from validation
63 errors appear earlier and benefit from a more detailed error type: 79 errors appear earlier and benefit from a more detailed error description:
64 80
65 ``` 81 ```
66 HTTP 1.1 400 Bad Request 82 HTTP 1.1 400 Bad Request
@@ -89,6 +105,12 @@ info:
89 `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg` 105 `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
90 is about. 106 is about.
91 107
108 ### Deprecated error fields
109
110 Some fields could be included with previous versions. They are still included but their use is deprecated:
111 - `error`: superseded by `detail`
112 - `code`: superseded by `type` (which is now an URI)
113
92 # Rate limits 114 # Rate limits
93 115
94 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators: 116 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
@@ -932,6 +954,12 @@ paths:
932 type: integer 954 type: integer
933 minimum: 0 955 minimum: 0
934 example: 1209600 956 example: 1209600
957 '400':
958 x-summary: client or credentials are invalid
959 description: |
960 Disambiguate via `type`:
961 - `invalid_client` for an unmatched `client_id`
962 - `invalid_grant` for unmatched credentials
935 x-codeSamples: 963 x-codeSamples:
936 - lang: Shell 964 - lang: Shell
937 source: | 965 source: |
@@ -1812,8 +1840,6 @@ paths:
1812 application/json: 1840 application/json:
1813 schema: 1841 schema:
1814 $ref: '#/components/schemas/VideoUploadResponse' 1842 $ref: '#/components/schemas/VideoUploadResponse'
1815 '400':
1816 description: invalid file field, schedule date or parameter
1817 '403': 1843 '403':
1818 description: video didn't pass upload filter 1844 description: video didn't pass upload filter
1819 '408': 1845 '408':
@@ -1918,8 +1944,6 @@ paths:
1918 schema: 1944 schema:
1919 type: number 1945 type: number
1920 example: 0 1946 example: 0
1921 '400':
1922 description: invalid file field, schedule date or parameter
1923 '413': 1947 '413':
1924 description: video file too large, due to quota, absolute max file size or concurrent partial upload limit 1948 description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1925 '415': 1949 '415':