Download as
Browse Code »

Commit 39114d259c6e4bd5bb60b18f561d06cc24e8c852

Authored by Sebastian Ziebell
1 parent b5ef6d22
Exists in master and in 4 other branches 6-8-stable, 7-0-stable, 7-0-stable-spb, spb-stable

API: documentation contains infos to status codes in README file. 

All the info to return codes from the API functions are available in the `README.md` file as suggested.
Showing 11 changed files with 36 additions and 475 deletions   Show diff stats
doc/api/README.md
  Diff comments   View file @39114d2
... ... @@ -27,6 +27,42 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/p
27 27  
28 28 The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL.
29 29  
  30 +
  31 +
  32 +## Status codes
  33 +
  34 +API requests return different status codes according to
  35 +
  36 +The API is designed to provide status codes according to the context and how the request
  37 +is handled. For example if a `GET` request is successful a status code `200 Ok`
  38 +is returned. The API is designed to be RESTful.
  39 +
  40 +The following list gives an overview of how the API functions are designed.
  41 +
  42 +API request types:
  43 +
  44 +* `GET` requests access one or more resources and return the result as JSON
  45 +* `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON
  46 +* `GET`, `PUT` and `DELETE` return `200 Ok` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON
  47 +* `DELETE` requests are designed to be idempotent, meaning a request a resource still returns `200 Ok` even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not.
  48 +
  49 +
  50 +The following list shows the possible return codes for API requests.
  51 +
  52 +Return values:
  53 +
  54 +* `200 Ok` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON
  55 +* `201 Created` - The `POST` request was successful and the resource is returned as JSON
  56 +* `400 Bad Request` - A required attribute of the API request is missing, e.g. the title of an issue is not given
  57 +* `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above
  58 +* `403 Forbidden` - The request is not allowed, e.g. the user is not allowed to delete a project
  59 +* `404 Not Found` - A resource could not be accessed, e.g. an ID for a resource could not be found
  60 +* `405 Method Not Allowed` - The request is not supported
  61 +* `409 Conflict` - A conflicting resource already exists, a project with same name already exists
  62 +* `500 Server Error` - While handling the request something went wrong on the server side
  63 +
  64 +
  65 +
30 66 #### Pagination
31 67  
32 68 When listing resources you can pass the following parameters:
... ...
doc/api/groups.md
  Diff comments   View file @39114d2
... ... @@ -17,12 +17,6 @@ GET /groups
17 17 ]
18 18 ```
19 19  
20   -Return values:
21   -
22   -+ `200 Ok` on success and list of groups
23   -+ `401 Unauthorized` if user is not authenticated
24   -+ `404 Not Found` if something fails
25   -
26 20  
27 21 ## Details of a group
28 22  
... ... @@ -36,12 +30,6 @@ Parameters:
36 30  
37 31 + `id` (required) - The ID of a group
38 32  
39   -Return values:
40   -
41   -+ `200 Ok` on success and the details of a group
42   -+ `401 Unauthorized` if user not authenticated
43   -+ `404 Not Found` if group ID not found
44   -
45 33  
46 34 ## New group
47 35  
... ... @@ -56,10 +44,3 @@ Parameters:
56 44 + `name` (required) - The name of the group
57 45 + `path` (required) - The path of the group
58 46  
59   -Return valueS:
60   -
61   -+ `201 Created` on success and the newly created group
62   -+ `400 Bad Request` if one of the required attributes not given
63   -+ `401 Unauthorized` if user is not authenticated
64   -+ `404 Not Found` if something fails
65   -
... ...
doc/api/issues.md
  Diff comments   View file @39114d2
... ... @@ -69,13 +69,6 @@ GET /issues
69 69 ]
70 70 ```
71 71  
72   -Return values:
73   -
74   -+ `200 Ok` on success and the list of issues
75   -+ `401 Unauthorized` if user is not authenticated
76   -+ `404 Not Found` if something fails
77   -
78   -
79 72  
80 73 ## List project issues
81 74  
... ... @@ -90,12 +83,6 @@ Parameters:
90 83  
91 84 + `id` (required) - The ID of a project
92 85  
93   -Return values:
94   -
95   -+ `200 Ok` on success and the list of project issues
96   -+ `401 Unauthorized` if user is not authenticated
97   -+ `404 Not Found` if project ID not found
98   -
99 86  
100 87 ## Single issue
101 88  
... ... @@ -150,12 +137,6 @@ Parameters:
150 137 }
151 138 ```
152 139  
153   -Return values:
154   -
155   -+ `200 Ok` on success and the list of project issues
156   -+ `401 Unauthorized` if user is not authenticated
157   -+ `404 Not Found` if project ID or issue ID not found
158   -
159 140  
160 141 ## New issue
161 142  
... ... @@ -174,13 +155,6 @@ Parameters:
174 155 + `milestone_id` (optional) - The ID of a milestone to assign issue
175 156 + `labels` (optional) - Comma-separated label names for an issue
176 157  
177   -Return values:
178   -
179   -+ `201 Created` on success and the newly created project issue
180   -+ `400 Bad Request` if the required attribute title is not given
181   -+ `401 Unauthorized` if user is not authenticated
182   -+ `404 Not Found` if project ID not found
183   -
184 158  
185 159 ## Edit issue
186 160  
... ... @@ -201,12 +175,6 @@ Parameters:
201 175 + `labels` (optional) - Comma-separated label names for an issue
202 176 + `closed` (optional) - The state of an issue (0 = false, 1 = true)
203 177  
204   -Return values:
205   -
206   -+ `200 Ok` on success and the update project issue
207   -+ `401 Unauthorized` if user is not authenticated
208   -+ `404 Not Found` if project ID or issue ID not found
209   -
210 178  
211 179 ## Delete existing issue (**Deprecated**)
212 180  
... ... @@ -223,6 +191,3 @@ Parameters:
223 191 + `id` (required) - The project ID
224 192 + `issue_id` (required) - The ID of the issue
225 193  
226   -Return values:
227   -
228   -+ `405 Method Not Allowed` is always returned, because the function is deprecated
... ...
doc/api/merge_requests.md
  Diff comments   View file @39114d2
... ... @@ -41,12 +41,6 @@ Parameters:
41 41 ]
42 42 ```
43 43  
44   -Return values:
45   -
46   -+ `200 Ok` on success and the list of merge requests
47   -+ `401 Unauthorized` if user is not authenticated
48   -+ `404 Not Found` if project ID not found
49   -
50 44  
51 45 ## Get single MR
52 46  
... ... @@ -89,12 +83,6 @@ Parameters:
89 83 }
90 84 ```
91 85  
92   -Return values:
93   -
94   -+ `200 Ok` on success and the single merge request
95   -+ `401 Unauthorized` if user is not authenticated
96   -+ `404 Not Found` if project ID or merge request ID not found
97   -
98 86  
99 87 ## Create MR
100 88  
... ... @@ -140,14 +128,6 @@ Parameters:
140 128 }
141 129 ```
142 130  
143   -Return values:
144   -
145   -+ `201 Created` on success and the created merge request
146   -+ `400 Bad Request` if one of the required attributes is missing
147   -+ `401 Unauthorize` if user is not authenticated or not allowed
148   -+ `403 Forbidden` if user is not allowed to create a merge request
149   -+ `404 Not Found` if project ID not found or something else fails
150   -
151 131  
152 132 ## Update MR
153 133  
... ... @@ -196,13 +176,6 @@ Parameters:
196 176 }
197 177 ```
198 178  
199   -Return values:
200   -
201   -+ `200 Ok` on success and the updated merge request
202   -+ `401 Unauthorize` if user is not authenticated or not allowed
203   -+ `403 Forbidden` if user is not allowed to update the merge request
204   -+ `404 Not Found` if project ID or merge request ID not found
205   -
206 179  
207 180 ## Post comment to MR
208 181  
... ... @@ -232,10 +205,3 @@ Parameters:
232 205 "note":"text1"
233 206 }
234 207 ```
235   -
236   -Return values:
237   -
238   -+ `201 Created` on success and the new comment
239   -+ `400 Bad Request` if the required attribute note is not given
240   -+ `401 Unauthorized` if user is not authenticated
241   -+ `404 Not Found` if project ID or merge request ID not found
... ...
doc/api/milestones.md
  Diff comments   View file @39114d2
... ... @@ -10,12 +10,6 @@ Parameters:
10 10  
11 11 + `id` (required) - The ID of a project
12 12  
13   -Return values:
14   -
15   -+ `200 Ok` on success and the list of project milestones
16   -+ `401 Unauthorized` if user is not authenticated
17   -+ `404 Not Found` if project ID not found
18   -
19 13  
20 14 ## Get single milestone
21 15  
... ... @@ -30,12 +24,6 @@ Parameters:
30 24 + `id` (required) - The ID of a project
31 25 + `milestone_id` (required) - The ID of a project milestone
32 26  
33   -Return values:
34   -
35   -+ `200 Ok` on success and the single milestone
36   -+ `401 Unauthorized` if user is not authenticated
37   -+ `404 Not Found` if project ID not found
38   -
39 27  
40 28 ## Create new milestone
41 29  
... ... @@ -52,13 +40,6 @@ Parameters:
52 40 + `description` (optional) - The description of the milestone
53 41 + `due_date` (optional) - The due date of the milestone
54 42  
55   -Return values:
56   -
57   -+ `201 Created` on success and the new milestone
58   -+ `400 Bad Request` if the required attribute title is not given
59   -+ `401 Unauthorized` if user is not authenticated
60   -+ `404 Not Found` if project ID not found
61   -
62 43  
63 44 ## Edit milestone
64 45  
... ... @@ -77,8 +58,3 @@ Parameters:
77 58 + `due_date` (optional) - The due date of the milestone
78 59 + `closed` (optional) - The status of the milestone
79 60  
80   -Return values:
81   -
82   -+ `200 Ok` on success and the updated milestone
83   -+ `401 Unauthorized` if user is not authenticated
84   -+ `404 Not Found` if project ID or milestone ID not found
... ...
doc/api/notes.md
  Diff comments   View file @39114d2
... ... @@ -30,11 +30,6 @@ Parameters:
30 30  
31 31 + `id` (required) - The ID of a project
32 32  
33   -Return values:
34   -
35   -+ `200 Ok` on success and a list of notes
36   -+ `401 Unauthorized` if user is not authorized to access this page
37   -
38 33  
39 34 ### Get single wall note
40 35  
... ... @@ -49,12 +44,6 @@ Parameters:
49 44 + `id` (required) - The ID of a project
50 45 + `note_id` (required) - The ID of a wall note
51 46  
52   -Return values:
53   -
54   -+ `200 Ok` on success and the wall note (see example at `GET /projects/:id/notes`)
55   -+ `401 Unauthorized` if user is not authenticated
56   -+ `404 Not Found` if note ID not found
57   -
58 47  
59 48 ### Create new wall note
60 49  
... ... @@ -69,14 +58,6 @@ Parameters:
69 58 + `id` (required) - The ID of a project
70 59 + `body` (required) - The content of a note
71 60  
72   -Return values:
73   -
74   -+ `201 Created` on success and the new wall note
75   -+ `400 Bad Request` if attribute body is not given
76   -+ `401 Unauthorized` if user is not authenticated
77   -+ `404 Not Found` if something else fails
78   -
79   -
80 61  
81 62 ## Issues
82 63  
... ... @@ -93,12 +74,6 @@ Parameters:
93 74 + `id` (required) - The ID of a project
94 75 + `issue_id` (required) - The ID of an issue
95 76  
96   -Return values:
97   -
98   -+ `200 Ok` on success and a list of notes for a single issue
99   -+ `401 Unauthorized` if user is not authenticated
100   -+ `404 Not Found` if project ID or issue ID not found
101   -
102 77  
103 78 ### Get single issue note
104 79  
... ... @@ -114,12 +89,6 @@ Parameters:
114 89 + `issue_id` (required) - The ID of a project issue
115 90 + `note_id` (required) - The ID of an issue note
116 91  
117   -Return values:
118   -
119   -+ `200 Ok` on success and the single issue note
120   -+ `401 Unauthorized` if user is not authenticated
121   -+ `404 Not Found` if project ID, issue ID or note ID is not found
122   -
123 92  
124 93 ### Create new issue note
125 94  
... ... @@ -135,14 +104,6 @@ Parameters:
135 104 + `issue_id` (required) - The ID of an issue
136 105 + `body` (required) - The content of a note
137 106  
138   -Return values:
139   -
140   -+ `201 Created` on succes and the created note
141   -+ `400 Bad Request` if the required attribute body is not given
142   -+ `401 Unauthorized` if the user is not authenticated
143   -+ `404 Not Found` if the project ID or the issue ID not found
144   -
145   -
146 107  
147 108 ## Snippets
148 109  
... ... @@ -159,12 +120,6 @@ Parameters:
159 120 + `id` (required) - The ID of a project
160 121 + `snippet_id` (required) - The ID of a project snippet
161 122  
162   -Return values:
163   -
164   -+ `200 Ok` on success and a list of notes for a single snippet
165   -+ `401 Unauthorized` if user is not authenticated
166   -+ `404 Not Found` if project ID or issue ID not found
167   -
168 123  
169 124 ### Get single snippet note
170 125  
... ... @@ -180,12 +135,6 @@ Parameters:
180 135 + `snippet_id` (required) - The ID of a project snippet
181 136 + `note_id` (required) - The ID of an snippet note
182 137  
183   -Return values:
184   -
185   -+ `200 Ok` on success and the single snippet note
186   -+ `401 Unauthorized` if user is not authenticated
187   -+ `404 Not Found` if project ID, snippet ID or note ID is not found
188   -
189 138  
190 139 ### Create new snippet note
191 140  
... ... @@ -201,14 +150,6 @@ Parameters:
201 150 + `snippet_id` (required) - The ID of an snippet
202 151 + `body` (required) - The content of a note
203 152  
204   -Return values:
205   -
206   -+ `201 Created` on success and the new snippet note
207   -+ `400 Bad Request` if the required attribute body not given
208   -+ `401 Unauthorized` if user is not authenticated
209   -+ `404 Not Found` if project ID or snippet ID not found
210   -
211   -
212 153  
213 154 ## Merge Requests
214 155  
... ... @@ -225,12 +166,6 @@ Parameters:
225 166 + `id` (required) - The ID of a project
226 167 + `merge_request_id` (required) - The ID of a project merge request
227 168  
228   -Return values:
229   -
230   -+ `200 Ok` on success and a list of notes for a single merge request
231   -+ `401 Unauthorized` if user is not authenticated
232   -+ `404 Not Found` if project ID or merge request ID not found
233   -
234 169  
235 170 ### Get single merge request note
236 171  
... ... @@ -246,12 +181,6 @@ Parameters:
246 181 + `merge_request_id` (required) - The ID of a project merge request
247 182 + `note_id` (required) - The ID of a merge request note
248 183  
249   -Return values:
250   -
251   -+ `200 Ok` on success and the single merge request note
252   -+ `401 Unauthorized` if user is not authenticated
253   -+ `404 Not Found` if project ID, merge request ID or note ID is not found
254   -
255 184  
256 185 ### Create new merge request note
257 186  
... ... @@ -267,10 +196,3 @@ Parameters:
267 196 + `merge_request_id` (required) - The ID of a merge request
268 197 + `body` (required) - The content of a note
269 198  
270   -Return values:
271   -
272   -+ `201 Created` on success and the new merge request note
273   -+ `400 Bad Request` if the required attribute body not given
274   -+ `401 Unauthorized` if user is not authenticated
275   -+ `404 Not Found` if project ID or merge request ID not found
276   -
... ...
doc/api/projects.md
  Diff comments   View file @39114d2
... ... @@ -57,11 +57,6 @@ GET /projects
57 57 ]
58 58 ```
59 59  
60   -Return values:
61   -
62   -+ `200 Ok` on success and a list of projects
63   -+ `401 Unauthorized` if the user is not allowed to access projects
64   -
65 60  
66 61 ### Get single project
67 62  
... ... @@ -101,11 +96,6 @@ Parameters:
101 96 }
102 97 ```
103 98  
104   -Return Values:
105   -
106   -+ `200 Ok` if the project with given ID is found and the JSON response
107   -+ `404 Not Found` if no project with ID found
108   -
109 99  
110 100 ### Create project
111 101  
... ... @@ -125,13 +115,6 @@ Parameters:
125 115 + `merge_requests_enabled` (optional) - enabled by default
126 116 + `wiki_enabled` (optional) - enabled by default
127 117  
128   -Return values:
129   -
130   -+ `201 Created` on success with the project data (see example at `GET /projects/:id`)
131   -+ `400 Bad Request` if the required attribute name is not given
132   -+ `403 Forbidden` if the user is not allowed to create a project, e.g. reached the project limit already
133   -+ `404 Not Found` if something else fails
134   -
135 118  
136 119 ## Project access levels
137 120  
... ... @@ -159,11 +142,6 @@ Parameters:
159 142 + `id` (required) - The ID or NAME of a project
160 143 + `query` - Query string
161 144  
162   -Return Values:
163   -
164   -+ `200 Ok` on success and a list of found team members
165   -+ `404 Not Found` if project with ID not found
166   -
167 145  
168 146 ## Team members
169 147  
... ... @@ -192,11 +170,6 @@ Parameters:
192 170 }
193 171 ```
194 172  
195   -Return Values:
196   -
197   -+ `200 Ok` on success and the team member, see example
198   -+ `404 Not Found` if either the project or the team member could not be found
199   -
200 173  
201 174 ### Add project team member
202 175  
... ... @@ -214,14 +187,6 @@ Parameters:
214 187 + `user_id` (required) - The ID of a user to add
215 188 + `access_level` (required) - Project access level
216 189  
217   -Return Values:
218   -
219   -+ `201 Created` on success and the added user is returned, even if the user is already team member
220   -+ `400 Bad Request` if the required attribute access_level is not given
221   -+ `401 Unauthorized` if the user is not allowed to add a new team member
222   -+ `404 Not Found` if a resource can not be found, e.g. project with ID not available
223   -+ `422 Unprocessable Entity` if an unknown access_level is given
224   -
225 190  
226 191 ### Edit project team member
227 192  
... ... @@ -237,14 +202,6 @@ Parameters:
237 202 + `user_id` (required) - The ID of a team member
238 203 + `access_level` (required) - Project access level
239 204  
240   -Return Values:
241   -
242   -+ `200 Ok` on succes and the modified team member
243   -+ `400 Bad Request` if the required attribute access_level is not given
244   -+ `401 Unauthorized` if the user is not allowed to modify a team member
245   -+ `404 Not Found` if a resource can not be found, e.g. project with ID not available
246   -+ `422 Unprocessable Entity` if an unknown access_level is given
247   -
248 205  
249 206 ### Remove project team member
250 207  
... ... @@ -259,12 +216,6 @@ Parameters:
259 216 + `id` (required) - The ID or NAME of a project
260 217 + `user_id` (required) - The ID of a team member
261 218  
262   -Return Values:
263   -
264   -+ `200 Ok` on success
265   -+ `401 Unauthorized` if user is not allowed to remove a team member
266   -+ `404 Not Found` if either project or user can not be found
267   -
268 219 This method is idempotent and can be called multiple times with the same parameters.
269 220 Revoking team membership for a user who is not currently a team member is considered success.
270 221 Please note that the returned JSON currently differs slightly. Thus you should not
... ... @@ -285,12 +236,6 @@ Parameters:
285 236  
286 237 + `id` (required) - The ID or NAME of a project
287 238  
288   -Return values:
289   -
290   -+ `200 Ok` on success with a list of hooks
291   -+ `401 Unauthorized` if user is not allowed to get list of hooks
292   -+ `404 Not Found` if project can not be found
293   -
294 239  
295 240 ### Get project hook
296 241  
... ... @@ -313,11 +258,6 @@ Parameters:
313 258 }
314 259 ```
315 260  
316   -Return values:
317   -
318   -+ `200 Ok` on sucess and the hook with the given ID
319   -+ `404 Not Found` if the hook can not be found
320   -
321 261  
322 262 ### Add project hook
323 263  
... ... @@ -332,13 +272,6 @@ Parameters:
332 272 + `id` (required) - The ID or NAME of a project
333 273 + `url` (required) - The hook URL
334 274  
335   -Return values:
336   -
337   -+ `201 Created` on success and the newly created hook
338   -+ `400 Bad Request` if url is not given
339   -+ `404 Not Found` if project with ID not found
340   -+ `422 Unprocessable Entity` if the url is invalid (must begin with `http` or `https`)
341   -
342 275  
343 276 ### Edit project hook
344 277  
... ... @@ -354,13 +287,6 @@ Parameters:
354 287 + `hook_id` (required) - The ID of a project hook
355 288 + `url` (required) - The hook URL
356 289  
357   -Return values:
358   -
359   -+ `200 Ok` on success and the modified hook (see JSON response above)
360   -+ `400 Bad Request` if the url attribute is not given
361   -+ `404 Not Found` if project or hook can not be found
362   -+ `422 Unprocessable Entity` if the url is invalid (must begin with `http` or `https`)
363   -
364 290  
365 291 ### Delete project hook
366 292  
... ... @@ -376,12 +302,6 @@ Parameters:
376 302 + `id` (required) - The ID or NAME of a project
377 303 + `hook_id` (required) - The ID of hook to delete
378 304  
379   -Return values:
380   -
381   -+ `200 Ok` on succes
382   -+ `403 Forbidden` if user is not allowed to delete a hook
383   -+ `404 Not Found` if the project can not be found
384   -
385 305 Note the JSON response differs if the hook is available or not. If the project hook
386 306 is available before it is returned in the JSON response or an empty response is returned.
387 307  
... ... @@ -400,11 +320,6 @@ Parameters:
400 320  
401 321 + `id` (required) - The ID of the project
402 322  
403   -Return values:
404   -
405   -+ `200 Ok` on success and a list of branches
406   -+ `404 Not Found` if project is not found
407   -
408 323  
409 324 ### List single branch
410 325  
... ... @@ -419,11 +334,6 @@ Parameters:
419 334 + `id` (required) - The ID of the project.
420 335 + `branch` (required) - The name of the branch.
421 336  
422   -Return values:
423   -
424   -+ `200 Ok` on success
425   -+ `404 Not Found` if either project with ID or branch could not be found
426   -
427 337  
428 338 ### Protect single branch
429 339  
... ... @@ -438,11 +348,6 @@ Parameters:
438 348 + `id` (required) - The ID of the project.
439 349 + `branch` (required) - The name of the branch.
440 350  
441   -Return values:
442   -
443   -+ `200 Ok` on success
444   -+ `404 Not Found` if either project or branch could not be found
445   -
446 351  
447 352 ### Unprotect single branch
448 353  
... ... @@ -457,11 +362,6 @@ Parameters:
457 362 + `id` (required) - The ID of the project.
458 363 + `branch` (required) - The name of the branch.
459 364  
460   -Return values:
461   -
462   -+ `200 Ok` on success
463   -+ `404 Not Found` if either project or branch could not be found
464   -
465 365  
466 366 ### List tags
467 367  
... ... @@ -475,11 +375,6 @@ Parameters:
475 375  
476 376 + `id` (required) - The ID of the project
477 377  
478   -Return values:
479   -
480   -+ `200 Ok` on success and a list of tags
481   -+ `404 Not Found` if project with id not found
482   -
483 378  
484 379 ### List commits
485 380  
... ... @@ -517,11 +412,6 @@ Parameters:
517 412  
518 413 + `id` (required) - The ID of the project
519 414  
520   -Return values:
521   -
522   -+ `200 Ok` on success and the list of snippets
523   -+ `404 Not Found` if project with id not found
524   -
525 415  
526 416 ### List single snippet
527 417  
... ... @@ -536,11 +426,6 @@ Parameters:
536 426 + `id` (required) - The ID of the project
537 427 + `snippet_id` (required) - The ID of the snippet
538 428  
539   -Return values:
540   -
541   -+ `200 Ok` on success and the project snippet
542   -+ `404 Not Found` if project ID or snippet ID not found
543   -
544 429  
545 430 ### Create snippet
546 431  
... ... @@ -558,13 +443,6 @@ Parameters:
558 443 + `code` (required) - The content of the snippet
559 444 + `lifetime` (optional) - The expiration date of a snippet
560 445  
561   -Return values:
562   -
563   -+ `201 Created` on success and the new snippet
564   -+ `400 Bad Request` if one of the required attributes is missing
565   -+ `401 Unauthorized` if it is not allowed to post a new snippet
566   -+ `404 Not Found` if the project ID is not found
567   -
568 446  
569 447 ### Update snippet
570 448  
... ... @@ -583,12 +461,6 @@ Parameters:
583 461 + `lifetime` (optional) - The new expiration date of the snippet
584 462 + `code` (optional) - The content of the snippet
585 463  
586   -Return values:
587   -
588   -+ `200 Ok` on success and the content of the updated snippet
589   -+ `401 Unauthorized` if the user is not allowed to modify the snippet
590   -+ `404 Not Found` if project ID or snippet ID is not found
591   -
592 464  
593 465 ## Delete snippet
594 466  
... ... @@ -604,8 +476,3 @@ Paramaters:
604 476 + `id` (required) - The ID of the project
605 477 + `snippet_id` (required) - The ID of the snippet
606 478  
607   -Return values:
608   -
609   -+ `200 Ok` on success, if the snippet got deleted it is returned, if not available then an empty JSON response
610   -+ `401 Unauthorized` if the user is not allowed to remove the snippet
611   -+ `404 Not Found` if the project ID not found
... ...
doc/api/repositories.md
  Diff comments   View file @39114d2
... ... @@ -39,12 +39,6 @@ Parameters:
39 39 ]
40 40 ```
41 41  
42   -Return values:
43   -
44   -+ `200 Ok`on success and a list of repository branches for the project
45   -+ `401 Unauthorized` if user is not authenticated
46   -+ `404 Not Found` if project with ID not found
47   -
48 42  
49 43 ## Get single repository branch
50 44  
... ... @@ -86,13 +80,6 @@ Parameters:
86 80 }
87 81 ```
88 82  
89   -Return values:
90   -
91   -+ `200 Ok` on success and the repository branch
92   -+ `401 Unauthorized` if user is not authenticated
93   -+ `404 Not Found` if the project ID or branch not found
94   -
95   -
96 83  
97 84 ## Protect repository branch
98 85  
... ... @@ -135,13 +122,6 @@ Parameters:
135 122 }
136 123 ```
137 124  
138   -Return values:
139   -
140   -+ `200 Ok` on success and the updated repository branch
141   -+ `401 Unauthorized` if user is not authenticated
142   -+ `404 Not Found` if the the project ID or branch not found
143   -
144   -
145 125  
146 126 ## Unprotect repository branch
147 127  
... ... @@ -184,13 +164,6 @@ Parameters:
184 164 }
185 165 ```
186 166  
187   -Return values:
188   -
189   -+ `200 Ok` on success and the updated repository branch
190   -+ `401 Unauthorized` if user is not authenticated
191   -+ `404 Not Found` if the project ID or the branch not found
192   -
193   -
194 167  
195 168 ## List project repository tags
196 169  
... ... @@ -231,12 +204,6 @@ Parameters:
231 204 ]
232 205 ```
233 206  
234   -Return values:
235   -
236   -+ `200 Ok` on success and the list of repository tags
237   -+ `401 Unauthorized` if user is not authenticated
238   -+ `404 Not Found` if the project ID not found
239   -
240 207  
241 208 ## List repository commits
242 209  
... ... @@ -274,12 +241,6 @@ Parameters:
274 241 ]
275 242 ```
276 243  
277   -Return values:
278   -
279   -+ `200 Ok` on success and a list of commits
280   -+ `401 Unauthorized` if the user is not authenticated
281   -+ `404 Not Found` if the project ID not found
282   -
283 244  
284 245 ## Raw blob content
285 246  
... ... @@ -294,11 +255,3 @@ Parameters:
294 255 + `id` (required) - The ID of a project
295 256 + `sha` (required) - The commit or branch name
296 257 + `filepath` (required) - The path the file
297   -
298   -Return values:
299   -
300   -+ `200 Ok` on success and the raw content of the file
301   -+ `400 Bad Request` if required attribute filepath is not given
302   -+ `401 Unauthorized` if user is not authenticated
303   -+ `404 Not Found` if project ID or sha commit or branch name not found
304   -
... ...
doc/api/session.md
  Diff comments   View file @39114d2
... ... @@ -21,8 +21,3 @@ Parameters:
21 21 "blocked": true
22 22 }
23 23 ```
24   -
25   -Return values:
26   -
27   -+ `201 Created` on success
28   -+ `401 Unauthorized` if the authentication process failed, e.g. invalid password or attribute not given
... ...
doc/api/snippets.md
  Diff comments   View file @39114d2
... ... @@ -10,11 +10,6 @@ Parameters:
10 10  
11 11 + `id` (required) - The ID of a project
12 12  
13   -Return values:
14   -
15   -+ `200 Ok` on success and a list of project snippets
16   -+ `401 Unauthorized` if user is not authenticated
17   -
18 13  
19 14 ## Single snippet
20 15  
... ... @@ -48,12 +43,6 @@ Parameters:
48 43 }
49 44 ```
50 45  
51   -Return values:
52   -
53   -+ `200 Ok` on success and the project snippet
54   -+ `401 Unauthorized` if user is not authenticated
55   -+ `404 Not Found` if snippet ID not found
56   -
57 46  
58 47 ## Create new snippet
59 48  
... ... @@ -71,13 +60,6 @@ Parameters:
71 60 + `lifetime` (optional) - The expiration date of a snippet
72 61 + `code` (required) - The content of a snippet
73 62  
74   -Return values:
75   -
76   -+ `201 Created` if snippet was successfully created and the snippet as JSON payload
77   -+ `400 Bad Request` if one of the required attributes is not given
78   -+ `401 Unauthorized` if user is not authenticated
79   -+ `404 Not Found` if project ID not found
80   -
81 63  
82 64 ## Edit snippet
83 65  
... ... @@ -96,12 +78,6 @@ Parameters:
96 78 + `lifetime` (optional) - The expiration date of a snippet
97 79 + `code` (optional) - The content of a snippet
98 80  
99   -Return values:
100   -
101   -+ `200 Ok` on success and the updated project snippet
102   -+ `401 Unauthorized` if user is not authenticated
103   -+ `404 Not Found` if project ID not found
104   -
105 81  
106 82 ## Delete snippet
107 83  
... ... @@ -117,12 +93,6 @@ Parameters:
117 93 + `id` (required) - The ID of a project
118 94 + `snippet_id` (required) - The ID of a project's snippet
119 95  
120   -Return values:
121   -
122   -+ `200 Ok` on success and if the snippet was deleted its content
123   -+ `401 Unauthorized` if user is not authenticated
124   -+ `404 Not Found` if project ID not found
125   -
126 96  
127 97 ## Snippet content
128 98  
... ... @@ -136,9 +106,3 @@ Parameters:
136 106  
137 107 + `id` (required) - The ID of a project
138 108 + `snippet_id` (required) - The ID of a project's snippet
139   -
140   -Return values:
141   -
142   -+ `200 Ok` on success and the raw snippet
143   -+ `401 Unauthorized` if user is not authenticated
144   -+ `404 Not Found` if project ID or snippet ID is not found
145 109 \ No newline at end of file
... ...
doc/api/users.md
  Diff comments   View file @39114d2
... ... @@ -43,11 +43,6 @@ GET /users
43 43 ]
44 44 ```
45 45  
46   -Return values:
47   -
48   -+ `200 Ok` on success and a list with all users
49   -+ `401 Unauthorized` if user is not allowed to access the list
50   -
51 46  
52 47 ## Single user
53 48  
... ... @@ -80,12 +75,6 @@ Parameters:
80 75 }
81 76 ```
82 77  
83   -Return values:
84   -
85   -+ `200 Ok` on success and the user entry
86   -+ `401 Unauthorized` if it is not allowed to access the user
87   -+ `404 Not Found` if the user with ID is not found
88   -
89 78  
90 79 ## User creation
91 80  
... ... @@ -109,15 +98,6 @@ Parameters:
109 98 + `provider` (optional) - External provider name
110 99 + `bio` (optional) - User's bio
111 100  
112   -Return values:
113   -
114   -+ `201 Created` on success and returns the new user
115   -+ `400 Bad Request` if one of the required attributes is missing from the request
116   -+ `401 Unauthorized` if the user is not authorized
117   -+ `403 Forbidden` if the user is not allowed to create a new user (must be admin)
118   -+ `404 Not Found` if something else fails
119   -+ `409 Conflict` if a user with the same email address or username already exists
120   -
121 101  
122 102 ## User modification
123 103  
... ... @@ -141,13 +121,6 @@ Parameters:
141 121 + `provider` - External provider name
142 122 + `bio` - User's bio
143 123  
144   -Return values:
145   -
146   -+ `200 Ok` on success and returns the new user
147   -+ `401 Unauthorized` if the user is not authorized
148   -+ `403 Forbidden` if the user is not allowed to create a new user (must be admin)
149   -+ `404 Not Found` if something else fails
150   -
151 124 Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would
152 125 be more appropriate, e.g. when renaming the email address to some exsisting one.
153 126  
... ... @@ -166,13 +139,6 @@ Parameters:
166 139  
167 140 + `id` (required) - The ID of the user
168 141  
169   -Return values:
170   -
171   -+ `200 Ok` on success and returns the deleted user
172   -+ `401 Unauthorized` if the user is not authorized
173   -+ `403 Forbidden` if the user is not allowed to create a new user (must be admin)
174   -+ `404 Not Found` if user with ID not found or something else fails
175   -
176 142  
177 143 ## Current user
178 144  
... ... @@ -199,12 +165,6 @@ GET /user
199 165 }
200 166 ```
201 167  
202   -Return values:
203   -
204   -+ `200 Ok` on success and returns the current user
205   -+ `401 Unauthorized` if the user is not authorized
206   -+ `404 Not Found` if something else fails
207   -
208 168  
209 169 ## List SSH keys
210 170  
... ... @@ -237,12 +197,6 @@ Parameters:
237 197  
238 198 + **none**
239 199  
240   -Return values:
241   -
242   -+ `200 Ok` on success and a list of ssh keys
243   -+ `401 Unauthorized` if the user is not authenticated
244   -+ `404 Not Found` if something else fails
245   -
246 200  
247 201 ## Single SSH key
248 202  
... ... @@ -266,12 +220,6 @@ Parameters:
266 220 }
267 221 ```
268 222  
269   -Return values:
270   -
271   -+ `200 Ok` on success and the ssh key with ID
272   -+ `401 Unauthorized` if it is not allowed to access the user
273   -+ `404 Not Found` if the ssh key with ID not found
274   -
275 223  
276 224 ## Add SSH key
277 225  
... ... @@ -286,13 +234,6 @@ Parameters:
286 234 + `title` (required) - new SSH Key's title
287 235 + `key` (required) - new SSH key
288 236  
289   -Return values:
290   -
291   -+ `201 Created` on success and the added key
292   -+ `400 Bad Request` if one of the required attributes is not given
293   -+ `401 Unauthorized` if user is not authorized to add ssh key
294   -+ `404 Not Found` if something else fails
295   -
296 237  
297 238 ## Delete SSH key
298 239  
... ... @@ -307,8 +248,3 @@ Parameters:
307 248  
308 249 + `id` (required) - SSH key ID
309 250  
310   -Return values:
311   -
312   -+ `200 Ok` on success
313   -+ `401 Unauthorized` if user is not allowed to delete they key
314   -+ `404 Not Found` if something else fails
... ...