Download as
Browse Code »

Commit 12a1f73b6126a3495c338287ad3ada0267657b4a

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

API projects documentation grouped into sections & updated with status codes 

The API documentation for projects now is structured into major sections that describe
the different aspects when dealing with projects, e.g. hooks, branches, team members etc.
All described methods now contain a list of possible status codes the method can return. A few
methods have extra sample JSON responses and a description if a method is idempotent.
Idempotent methods can be called multiple times while returning the same status code.
Showing 1 changed file with 117 additions and 34 deletions   Show diff stats
doc/api/projects.md
  Diff comments   View file @12a1f73
1   -## List projects
  1 +## Projects
  2 +
  3 +### List projects
2 4  
3 5 Get a list of projects owned by the authenticated user.
4 6  
... ... @@ -55,7 +57,8 @@ GET /projects
55 57 ]
56 58 ```
57 59  
58   -## Single project
  60 +
  61 +### Get single project
59 62  
60 63 Get a specific project, identified by project ID, which is owned by the authentication user.
61 64  
... ... @@ -92,9 +95,15 @@ Parameters:
92 95 }
93 96 ```
94 97  
95   -## Create project
  98 +Return Values:
  99 +
  100 ++ `200 Ok` if the project with given ID is found and the JSON response
  101 ++ `404 Not Found` if no project with ID found
  102 +
  103 +
  104 +### Create project
96 105  
97   -Create new project owned by user
  106 +Creates new project owned by user.
98 107  
99 108 ```
100 109 POST /projects
... ... @@ -110,10 +119,15 @@ Parameters:
110 119 + `merge_requests_enabled` (optional) - enabled by default
111 120 + `wiki_enabled` (optional) - enabled by default
112 121  
113   -Will return created project with status `201 Created` on success, or `404 Not
114   -found` on fail.
  122 +Return values:
115 123  
116   -## List project team members
  124 ++ `201 Created` on success with the project data (see example at `GET /projects/:id`)
  125 ++ `400 Bad Request` if the required attribute name is not given
  126 ++ `403 Forbidden` if the user is not allowed to create a project, e.g. reached the project limit already
  127 ++ `404 Not Found` if something else fails
  128 +
  129 +
  130 +### List project members
117 131  
118 132 Get a list of project team members.
119 133  
... ... @@ -126,7 +140,15 @@ Parameters:
126 140 + `id` (required) - The ID of a project
127 141 + `query` - Query string
128 142  
129   -## Get project team member
  143 +Return Values:
  144 +
  145 ++ `200 Ok` on success and a list of found team members
  146 ++ `404 Not Found` if project with ID not found
  147 +
  148 +
  149 +## Team members
  150 +
  151 +### Get project team member
130 152  
131 153 Get a project team member.
132 154  
... ... @@ -141,7 +163,6 @@ Parameters:
141 163  
142 164 ```json
143 165 {
144   -
145 166 "id": 1,
146 167 "username": "john_smith",
147 168 "email": "john@example.com",
... ... @@ -152,9 +173,17 @@ Parameters:
152 173 }
153 174 ```
154 175  
155   -## Add project team member
  176 +Return Values:
  177 +
  178 ++ `200 Ok` on success and the team member, see example
  179 ++ `404 Not Found` if either the project or the team member could not be found
  180 +
  181 +
  182 +### Add project team member
156 183  
157   -Add a user to a project team.
  184 +Adds a user to a project team. This is an idempotent method and can be called multiple times
  185 +with the same parameters. Adding team membership to a user that is already a member does not
  186 +affect the membership.
158 187  
159 188 ```
160 189 POST /projects/:id/members
... ... @@ -166,9 +195,15 @@ Parameters:
166 195 + `user_id` (required) - The ID of a user to add
167 196 + `access_level` (required) - Project access level
168 197  
169   -Will return status `201 Created` on success, or `404 Not found` on fail.
  198 +Return Values:
170 199  
171   -## Edit project team member
  200 ++ `200 Ok` on success and the added user, even if the user is already team member
  201 ++ `400 Bad Request` if the required attribute access_level is not given
  202 ++ `404 Not Found` if a resource can not be found, e.g. project with ID not available
  203 ++ `422 Unprocessable Entity` if an unknown access_level is given
  204 +
  205 +
  206 +### Edit project team member
172 207  
173 208 Update project team member to specified access level.
174 209  
... ... @@ -182,9 +217,15 @@ Parameters:
182 217 + `user_id` (required) - The ID of a team member
183 218 + `access_level` (required) - Project access level
184 219  
185   -Will return status `200 OK` on success, or `404 Not found` on fail.
  220 +Return Values:
  221 +
  222 ++ `200 Ok` on succes and the modified team member
  223 ++ `400 Bad Request` if the required attribute access_level is not given
  224 ++ `404 Not Found` if a resource can not be found, e.g. project with ID not available
  225 ++ `422 Unprocessable Entity` if an unknown access_level is given
186 226  
187   -## Remove project team member
  227 +
  228 +### Remove project team member
188 229  
189 230 Removes user from project team.
190 231  
... ... @@ -197,14 +238,22 @@ Parameters:
197 238 + `id` (required) - The ID of a project
198 239 + `user_id` (required) - The ID of a team member
199 240  
200   -Status code `200 OK` will be returned on success. This method is idempotent and call be called multiple
201   -times with the same parameters. Revoking team membership for a user who is not currently a team member is
202   -considered success. Please note that the returned JSON currently differs slightly. Thus you should not
  241 +Return Values:
  242 +
  243 ++ `200 Ok` on success
  244 ++ `404 Not Found` if either project or user can not be found
  245 +
  246 +This method is idempotent and can be called multiple times with the same parameters.
  247 +Revoking team membership for a user who is not currently a team member is considered success.
  248 +Please note that the returned JSON currently differs slightly. Thus you should not
203 249 rely on the returned JSON structure.
204 250  
205   -## List project hooks
206 251  
207   -Get list for project hooks
  252 +## Hooks
  253 +
  254 +### List project hooks
  255 +
  256 +Get list of project hooks.
208 257  
209 258 ```
210 259 GET /projects/:id/hooks
... ... @@ -214,26 +263,42 @@ Parameters:
214 263  
215 264 + `id` (required) - The ID of a project
216 265  
217   -Will return hooks with status `200 OK` on success, or `404 Not found` on fail.
  266 +Return values:
  267 +
  268 ++ `200 Ok` on success with a list of hooks
  269 ++ `404 Not Found` if project can not be found
  270 +
218 271  
219   -## Get project hook
  272 +### Get project hook
220 273  
221   -Get hook for project
  274 +Get a specific hook for project.
222 275  
223 276 ```
224 277 GET /projects/:id/hooks/:hook_id
225 278 ```
226 279  
227   -Parameters:§
  280 +Parameters:
228 281  
229 282 + `id` (required) - The ID of a project
230 283 + `hook_id` (required) - The ID of a project hook
231 284  
232   -Will return hook with status `200 OK` on success, or `404 Not found` on fail.
  285 +```json
  286 +{
  287 + "id": 1,
  288 + "url": "http://example.com/hook",
  289 + "created_at": "2012-10-12T17:04:47Z"
  290 +}
  291 +```
  292 +
  293 +Return values:
  294 +
  295 ++ `200 Ok` on sucess and the hook with the given ID
  296 ++ `404 Not Found` if the hook can not be found
233 297  
234   -## Add project hook
235 298  
236   -Add hook to project
  299 +### Add project hook
  300 +
  301 +Adds a hook to project.
237 302  
238 303 ```
239 304 POST /projects/:id/hooks
... ... @@ -244,11 +309,17 @@ Parameters:
244 309 + `id` (required) - The ID of a project
245 310 + `url` (required) - The hook URL
246 311  
247   -Will return status `201 Created` on success, or `404 Not found` on fail.
  312 +Return values:
  313 +
  314 ++ `201 Created` on success and the newly created hook
  315 ++ `400 Bad Request` if url is not given
  316 ++ `404 Not Found` if project with ID not found
  317 ++ `422 Unprocessable Entity` if the url is invalid (must begin with `http` or `https`)
248 318  
249   -## Edit project hook
250 319  
251   -Edit hook for project
  320 +### Edit project hook
  321 +
  322 +Edits a hook for project.
252 323  
253 324 ```
254 325 PUT /projects/:id/hooks/:hook_id
... ... @@ -260,12 +331,18 @@ Parameters:
260 331 + `hook_id` (required) - The ID of a project hook
261 332 + `url` (required) - The hook URL
262 333  
263   -Will return status `201 Created` on success, or `404 Not found` on fail.
  334 +Return values:
  335 +
  336 ++ `200 Ok` on success and the modified hook (see JSON response above)
  337 ++ `400 Bad Request` if the url attribute is not given
  338 ++ `404 Not Found` if project or hook can not be found
  339 ++ `422 Unprocessable Entity` if the url is invalid (must begin with `http` or `https`)
264 340  
265 341  
266   -## Delete project hook
  342 +### Delete project hook
267 343  
268   -Delete hook from project
  344 +Removes a hook from project. This is an idempotent method and can be called multiple times.
  345 +Either the hook is available or not.
269 346  
270 347 ```
271 348 DELETE /projects/:id/hooks
... ... @@ -276,4 +353,10 @@ Parameters:
276 353 + `id` (required) - The ID of a project
277 354 + `hook_id` (required) - The ID of hook to delete
278 355  
279   -Will return status `200 OK` on success, or `404 Not found` on fail.
  356 +Return values:
  357 +
  358 ++ `200 Ok` on succes
  359 ++ `404 Not Found` if the project can not be found
  360 +
  361 +Note the JSON response differs if the hook is available or not. If the project hook
  362 +is available before it is returned in the JSON response or an empty response is returned.
... ...