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,6 +27,42 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/p
27 27
28 The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL. 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 #### Pagination 66 #### Pagination
31 67
32 When listing resources you can pass the following parameters: 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,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 ## Details of a group 21 ## Details of a group
28 22
@@ -36,12 +30,6 @@ Parameters: @@ -36,12 +30,6 @@ Parameters:
36 30
37 + `id` (required) - The ID of a group 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 ## New group 34 ## New group
47 35
@@ -56,10 +44,3 @@ Parameters: @@ -56,10 +44,3 @@ Parameters:
56 + `name` (required) - The name of the group 44 + `name` (required) - The name of the group
57 + `path` (required) - The path of the group 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,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 ## List project issues 73 ## List project issues
81 74
@@ -90,12 +83,6 @@ Parameters: @@ -90,12 +83,6 @@ Parameters:
90 83
91 + `id` (required) - The ID of a project 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 ## Single issue 87 ## Single issue
101 88
@@ -150,12 +137,6 @@ Parameters: @@ -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 ## New issue 141 ## New issue
161 142
@@ -174,13 +155,6 @@ Parameters: @@ -174,13 +155,6 @@ Parameters:
174 + `milestone_id` (optional) - The ID of a milestone to assign issue 155 + `milestone_id` (optional) - The ID of a milestone to assign issue
175 + `labels` (optional) - Comma-separated label names for an issue 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 ## Edit issue 159 ## Edit issue
186 160
@@ -201,12 +175,6 @@ Parameters: @@ -201,12 +175,6 @@ Parameters:
201 + `labels` (optional) - Comma-separated label names for an issue 175 + `labels` (optional) - Comma-separated label names for an issue
202 + `closed` (optional) - The state of an issue (0 = false, 1 = true) 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 ## Delete existing issue (**Deprecated**) 179 ## Delete existing issue (**Deprecated**)
212 180
@@ -223,6 +191,3 @@ Parameters: @@ -223,6 +191,3 @@ Parameters:
223 + `id` (required) - The project ID 191 + `id` (required) - The project ID
224 + `issue_id` (required) - The ID of the issue 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,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 ## Get single MR 45 ## Get single MR
52 46
@@ -89,12 +83,6 @@ Parameters: @@ -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 ## Create MR 87 ## Create MR
100 88
@@ -140,14 +128,6 @@ Parameters: @@ -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 ## Update MR 132 ## Update MR
153 133
@@ -196,13 +176,6 @@ Parameters: @@ -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 ## Post comment to MR 180 ## Post comment to MR
208 181
@@ -232,10 +205,3 @@ Parameters: @@ -232,10 +205,3 @@ Parameters:
232 "note":"text1" 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,12 +10,6 @@ Parameters:
10 10
11 + `id` (required) - The ID of a project 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 ## Get single milestone 14 ## Get single milestone
21 15
@@ -30,12 +24,6 @@ Parameters: @@ -30,12 +24,6 @@ Parameters:
30 + `id` (required) - The ID of a project 24 + `id` (required) - The ID of a project
31 + `milestone_id` (required) - The ID of a project milestone 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 ## Create new milestone 28 ## Create new milestone
41 29
@@ -52,13 +40,6 @@ Parameters: @@ -52,13 +40,6 @@ Parameters:
52 + `description` (optional) - The description of the milestone 40 + `description` (optional) - The description of the milestone
53 + `due_date` (optional) - The due date of the milestone 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 ## Edit milestone 44 ## Edit milestone
64 45
@@ -77,8 +58,3 @@ Parameters: @@ -77,8 +58,3 @@ Parameters:
77 + `due_date` (optional) - The due date of the milestone 58 + `due_date` (optional) - The due date of the milestone
78 + `closed` (optional) - The status of the milestone 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,11 +30,6 @@ Parameters:
30 30
31 + `id` (required) - The ID of a project 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 ### Get single wall note 34 ### Get single wall note
40 35
@@ -49,12 +44,6 @@ Parameters: @@ -49,12 +44,6 @@ Parameters:
49 + `id` (required) - The ID of a project 44 + `id` (required) - The ID of a project
50 + `note_id` (required) - The ID of a wall note 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 ### Create new wall note 48 ### Create new wall note
60 49
@@ -69,14 +58,6 @@ Parameters: @@ -69,14 +58,6 @@ Parameters:
69 + `id` (required) - The ID of a project 58 + `id` (required) - The ID of a project
70 + `body` (required) - The content of a note 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 ## Issues 62 ## Issues
82 63
@@ -93,12 +74,6 @@ Parameters: @@ -93,12 +74,6 @@ Parameters:
93 + `id` (required) - The ID of a project 74 + `id` (required) - The ID of a project
94 + `issue_id` (required) - The ID of an issue 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 ### Get single issue note 78 ### Get single issue note
104 79
@@ -114,12 +89,6 @@ Parameters: @@ -114,12 +89,6 @@ Parameters:
114 + `issue_id` (required) - The ID of a project issue 89 + `issue_id` (required) - The ID of a project issue
115 + `note_id` (required) - The ID of an issue note 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 ### Create new issue note 93 ### Create new issue note
125 94
@@ -135,14 +104,6 @@ Parameters: @@ -135,14 +104,6 @@ Parameters:
135 + `issue_id` (required) - The ID of an issue 104 + `issue_id` (required) - The ID of an issue
136 + `body` (required) - The content of a note 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 ## Snippets 108 ## Snippets
148 109
@@ -159,12 +120,6 @@ Parameters: @@ -159,12 +120,6 @@ Parameters:
159 + `id` (required) - The ID of a project 120 + `id` (required) - The ID of a project
160 + `snippet_id` (required) - The ID of a project snippet 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 ### Get single snippet note 124 ### Get single snippet note
170 125
@@ -180,12 +135,6 @@ Parameters: @@ -180,12 +135,6 @@ Parameters:
180 + `snippet_id` (required) - The ID of a project snippet 135 + `snippet_id` (required) - The ID of a project snippet
181 + `note_id` (required) - The ID of an snippet note 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 ### Create new snippet note 139 ### Create new snippet note
191 140
@@ -201,14 +150,6 @@ Parameters: @@ -201,14 +150,6 @@ Parameters:
201 + `snippet_id` (required) - The ID of an snippet 150 + `snippet_id` (required) - The ID of an snippet
202 + `body` (required) - The content of a note 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 ## Merge Requests 154 ## Merge Requests
214 155
@@ -225,12 +166,6 @@ Parameters: @@ -225,12 +166,6 @@ Parameters:
225 + `id` (required) - The ID of a project 166 + `id` (required) - The ID of a project
226 + `merge_request_id` (required) - The ID of a project merge request 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 ### Get single merge request note 170 ### Get single merge request note
236 171
@@ -246,12 +181,6 @@ Parameters: @@ -246,12 +181,6 @@ Parameters:
246 + `merge_request_id` (required) - The ID of a project merge request 181 + `merge_request_id` (required) - The ID of a project merge request
247 + `note_id` (required) - The ID of a merge request note 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 ### Create new merge request note 185 ### Create new merge request note
257 186
@@ -267,10 +196,3 @@ Parameters: @@ -267,10 +196,3 @@ Parameters:
267 + `merge_request_id` (required) - The ID of a merge request 196 + `merge_request_id` (required) - The ID of a merge request
268 + `body` (required) - The content of a note 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,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 ### Get single project 61 ### Get single project
67 62
@@ -101,11 +96,6 @@ Parameters: @@ -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 ### Create project 100 ### Create project
111 101
@@ -125,13 +115,6 @@ Parameters: @@ -125,13 +115,6 @@ Parameters:
125 + `merge_requests_enabled` (optional) - enabled by default 115 + `merge_requests_enabled` (optional) - enabled by default
126 + `wiki_enabled` (optional) - enabled by default 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 ## Project access levels 119 ## Project access levels
137 120
@@ -159,11 +142,6 @@ Parameters: @@ -159,11 +142,6 @@ Parameters:
159 + `id` (required) - The ID or NAME of a project 142 + `id` (required) - The ID or NAME of a project
160 + `query` - Query string 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 ## Team members 146 ## Team members
169 147
@@ -192,11 +170,6 @@ Parameters: @@ -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 ### Add project team member 174 ### Add project team member
202 175
@@ -214,14 +187,6 @@ Parameters: @@ -214,14 +187,6 @@ Parameters:
214 + `user_id` (required) - The ID of a user to add 187 + `user_id` (required) - The ID of a user to add
215 + `access_level` (required) - Project access level 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 ### Edit project team member 191 ### Edit project team member
227 192
@@ -237,14 +202,6 @@ Parameters: @@ -237,14 +202,6 @@ Parameters:
237 + `user_id` (required) - The ID of a team member 202 + `user_id` (required) - The ID of a team member
238 + `access_level` (required) - Project access level 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 ### Remove project team member 206 ### Remove project team member
250 207
@@ -259,12 +216,6 @@ Parameters: @@ -259,12 +216,6 @@ Parameters:
259 + `id` (required) - The ID or NAME of a project 216 + `id` (required) - The ID or NAME of a project
260 + `user_id` (required) - The ID of a team member 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 This method is idempotent and can be called multiple times with the same parameters. 219 This method is idempotent and can be called multiple times with the same parameters.
269 Revoking team membership for a user who is not currently a team member is considered success. 220 Revoking team membership for a user who is not currently a team member is considered success.
270 Please note that the returned JSON currently differs slightly. Thus you should not 221 Please note that the returned JSON currently differs slightly. Thus you should not
@@ -285,12 +236,6 @@ Parameters: @@ -285,12 +236,6 @@ Parameters:
285 236
286 + `id` (required) - The ID or NAME of a project 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 ### Get project hook 240 ### Get project hook
296 241
@@ -313,11 +258,6 @@ Parameters: @@ -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 ### Add project hook 262 ### Add project hook
323 263
@@ -332,13 +272,6 @@ Parameters: @@ -332,13 +272,6 @@ Parameters:
332 + `id` (required) - The ID or NAME of a project 272 + `id` (required) - The ID or NAME of a project
333 + `url` (required) - The hook URL 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 ### Edit project hook 276 ### Edit project hook
344 277
@@ -354,13 +287,6 @@ Parameters: @@ -354,13 +287,6 @@ Parameters:
354 + `hook_id` (required) - The ID of a project hook 287 + `hook_id` (required) - The ID of a project hook
355 + `url` (required) - The hook URL 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 ### Delete project hook 291 ### Delete project hook
366 292
@@ -376,12 +302,6 @@ Parameters: @@ -376,12 +302,6 @@ Parameters:
376 + `id` (required) - The ID or NAME of a project 302 + `id` (required) - The ID or NAME of a project
377 + `hook_id` (required) - The ID of hook to delete 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 Note the JSON response differs if the hook is available or not. If the project hook 305 Note the JSON response differs if the hook is available or not. If the project hook
386 is available before it is returned in the JSON response or an empty response is returned. 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,11 +320,6 @@ Parameters:
400 320
401 + `id` (required) - The ID of the project 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 ### List single branch 324 ### List single branch
410 325
@@ -419,11 +334,6 @@ Parameters: @@ -419,11 +334,6 @@ Parameters:
419 + `id` (required) - The ID of the project. 334 + `id` (required) - The ID of the project.
420 + `branch` (required) - The name of the branch. 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 ### Protect single branch 338 ### Protect single branch
429 339
@@ -438,11 +348,6 @@ Parameters: @@ -438,11 +348,6 @@ Parameters:
438 + `id` (required) - The ID of the project. 348 + `id` (required) - The ID of the project.
439 + `branch` (required) - The name of the branch. 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 ### Unprotect single branch 352 ### Unprotect single branch
448 353
@@ -457,11 +362,6 @@ Parameters: @@ -457,11 +362,6 @@ Parameters:
457 + `id` (required) - The ID of the project. 362 + `id` (required) - The ID of the project.
458 + `branch` (required) - The name of the branch. 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 ### List tags 366 ### List tags
467 367
@@ -475,11 +375,6 @@ Parameters: @@ -475,11 +375,6 @@ Parameters:
475 375
476 + `id` (required) - The ID of the project 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 ### List commits 379 ### List commits
485 380
@@ -517,11 +412,6 @@ Parameters: @@ -517,11 +412,6 @@ Parameters:
517 412
518 + `id` (required) - The ID of the project 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 ### List single snippet 416 ### List single snippet
527 417
@@ -536,11 +426,6 @@ Parameters: @@ -536,11 +426,6 @@ Parameters:
536 + `id` (required) - The ID of the project 426 + `id` (required) - The ID of the project
537 + `snippet_id` (required) - The ID of the snippet 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 ### Create snippet 430 ### Create snippet
546 431
@@ -558,13 +443,6 @@ Parameters: @@ -558,13 +443,6 @@ Parameters:
558 + `code` (required) - The content of the snippet 443 + `code` (required) - The content of the snippet
559 + `lifetime` (optional) - The expiration date of a snippet 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 ### Update snippet 447 ### Update snippet
570 448
@@ -583,12 +461,6 @@ Parameters: @@ -583,12 +461,6 @@ Parameters:
583 + `lifetime` (optional) - The new expiration date of the snippet 461 + `lifetime` (optional) - The new expiration date of the snippet
584 + `code` (optional) - The content of the snippet 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 ## Delete snippet 465 ## Delete snippet
594 466
@@ -604,8 +476,3 @@ Paramaters: @@ -604,8 +476,3 @@ Paramaters:
604 + `id` (required) - The ID of the project 476 + `id` (required) - The ID of the project
605 + `snippet_id` (required) - The ID of the snippet 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,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 ## Get single repository branch 43 ## Get single repository branch
50 44
@@ -86,13 +80,6 @@ Parameters: @@ -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 ## Protect repository branch 84 ## Protect repository branch
98 85
@@ -135,13 +122,6 @@ Parameters: @@ -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 ## Unprotect repository branch 126 ## Unprotect repository branch
147 127
@@ -184,13 +164,6 @@ Parameters: @@ -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 ## List project repository tags 168 ## List project repository tags
196 169
@@ -231,12 +204,6 @@ Parameters: @@ -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 ## List repository commits 208 ## List repository commits
242 209
@@ -274,12 +241,6 @@ Parameters: @@ -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 ## Raw blob content 245 ## Raw blob content
285 246
@@ -294,11 +255,3 @@ Parameters: @@ -294,11 +255,3 @@ Parameters:
294 + `id` (required) - The ID of a project 255 + `id` (required) - The ID of a project
295 + `sha` (required) - The commit or branch name 256 + `sha` (required) - The commit or branch name
296 + `filepath` (required) - The path the file 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,8 +21,3 @@ Parameters:
21 "blocked": true 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,11 +10,6 @@ Parameters:
10 10
11 + `id` (required) - The ID of a project 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 ## Single snippet 14 ## Single snippet
20 15
@@ -48,12 +43,6 @@ Parameters: @@ -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 ## Create new snippet 47 ## Create new snippet
59 48
@@ -71,13 +60,6 @@ Parameters: @@ -71,13 +60,6 @@ Parameters:
71 + `lifetime` (optional) - The expiration date of a snippet 60 + `lifetime` (optional) - The expiration date of a snippet
72 + `code` (required) - The content of a snippet 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 ## Edit snippet 64 ## Edit snippet
83 65
@@ -96,12 +78,6 @@ Parameters: @@ -96,12 +78,6 @@ Parameters:
96 + `lifetime` (optional) - The expiration date of a snippet 78 + `lifetime` (optional) - The expiration date of a snippet
97 + `code` (optional) - The content of a snippet 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 ## Delete snippet 82 ## Delete snippet
107 83
@@ -117,12 +93,6 @@ Parameters: @@ -117,12 +93,6 @@ Parameters:
117 + `id` (required) - The ID of a project 93 + `id` (required) - The ID of a project
118 + `snippet_id` (required) - The ID of a project's snippet 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 ## Snippet content 97 ## Snippet content
128 98
@@ -136,9 +106,3 @@ Parameters: @@ -136,9 +106,3 @@ Parameters:
136 106
137 + `id` (required) - The ID of a project 107 + `id` (required) - The ID of a project
138 + `snippet_id` (required) - The ID of a project's snippet 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 \ No newline at end of file 109 \ No newline at end of file
doc/api/users.md
  Diff comments   View file @39114d2
@@ -43,11 +43,6 @@ GET /users @@ -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 ## Single user 47 ## Single user
53 48
@@ -80,12 +75,6 @@ Parameters: @@ -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 ## User creation 79 ## User creation
91 80
@@ -109,15 +98,6 @@ Parameters: @@ -109,15 +98,6 @@ Parameters:
109 + `provider` (optional) - External provider name 98 + `provider` (optional) - External provider name
110 + `bio` (optional) - User's bio 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 ## User modification 102 ## User modification
123 103
@@ -141,13 +121,6 @@ Parameters: @@ -141,13 +121,6 @@ Parameters:
141 + `provider` - External provider name 121 + `provider` - External provider name
142 + `bio` - User's bio 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 Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would 124 Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would
152 be more appropriate, e.g. when renaming the email address to some exsisting one. 125 be more appropriate, e.g. when renaming the email address to some exsisting one.
153 126
@@ -166,13 +139,6 @@ Parameters: @@ -166,13 +139,6 @@ Parameters:
166 139
167 + `id` (required) - The ID of the user 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 ## Current user 143 ## Current user
178 144
@@ -199,12 +165,6 @@ GET /user @@ -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 ## List SSH keys 169 ## List SSH keys
210 170
@@ -237,12 +197,6 @@ Parameters: @@ -237,12 +197,6 @@ Parameters:
237 197
238 + **none** 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 ## Single SSH key 201 ## Single SSH key
248 202
@@ -266,12 +220,6 @@ Parameters: @@ -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 ## Add SSH key 224 ## Add SSH key
277 225
@@ -286,13 +234,6 @@ Parameters: @@ -286,13 +234,6 @@ Parameters:
286 + `title` (required) - new SSH Key's title 234 + `title` (required) - new SSH Key's title
287 + `key` (required) - new SSH key 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 ## Delete SSH key 238 ## Delete SSH key
298 239
@@ -307,8 +248,3 @@ Parameters: @@ -307,8 +248,3 @@ Parameters:
307 248
308 + `id` (required) - SSH key ID 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