Download as
Browse Code »

Commit e119b0a0cb33b1b7f2dafcf17c2a94af40aed833

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

API repository documentation updated, includes infos to return codes 

The API documentation of repository is updated and now contains infos to status codes.
Code documentation is also adjusted for `GET /projects/:id/repository/commits` and includes infos to
pagination attributes. Tests are updated.
Showing 3 changed files with 73 additions and 25 deletions   Show diff stats
doc/api/repositories.md
  Diff comments   View file @e119b0a
1   -## Project repository branches
  1 +## List repository branches
2 2  
3 3 Get a list of repository branches from a project, sorted by name alphabetically.
4 4  
... ... @@ -39,7 +39,14 @@ Parameters:
39 39 ]
40 40 ```
41 41  
42   -## Project repository branch
  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 +
  49 +## Get single repository branch
43 50  
44 51 Get a single project repository branch.
45 52  
... ... @@ -79,12 +86,18 @@ Parameters:
79 86 }
80 87 ```
81 88  
82   -Will return status code `200` on success or `404 Not found` if the branch is not available.
  89 +Return values:
83 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
84 94  
85   -## Protect a project repository branch
86 95  
87   -Protect a single project repository branch.
  96 +
  97 +## Protect repository branch
  98 +
  99 +Protects a single project repository branch. This is an idempotent function, protecting an already
  100 +protected repository branch still returns a `200 Ok` status code.
88 101  
89 102 ```
90 103 PUT /projects/:id/repository/branches/:branch/protect
... ... @@ -122,9 +135,18 @@ Parameters:
122 135 }
123 136 ```
124 137  
125   -## Unprotect a project repository branch
  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
126 143  
127   -Unprotect a single project repository branch.
  144 +
  145 +
  146 +## Unprotect repository branch
  147 +
  148 +Unprotects a single project repository branch. This is an idempotent function, unprotecting an already
  149 +unprotected repository branch still returns a `200 Ok` status code.
128 150  
129 151 ```
130 152 PUT /projects/:id/repository/branches/:branch/unprotect
... ... @@ -162,7 +184,15 @@ Parameters:
162 184 }
163 185 ```
164 186  
165   -## Project repository tags
  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 +
  195 +## List project repository tags
166 196  
167 197 Get a list of repository tags from a project, sorted by name in reverse alphabetical order.
168 198  
... ... @@ -201,7 +231,14 @@ Parameters:
201 231 ]
202 232 ```
203 233  
204   -## Project repository commits
  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 +
  241 +## List repository commits
205 242  
206 243 Get a list of repository commits in a project.
207 244  
... ... @@ -212,7 +249,9 @@ GET /projects/:id/repository/commits
212 249 Parameters:
213 250  
214 251 + `id` (required) - The ID of a project
215   -+ `ref_name` (optional) - The name of a repository branch or tag
  252 ++ `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch
  253 ++ `page`(optional) - The page with the commits (pagination)
  254 ++ `per_page` (optional) - The number of commits per page (pagination)
216 255  
217 256 ```json
218 257 [
... ... @@ -235,6 +274,13 @@ Parameters:
235 274 ]
236 275 ```
237 276  
  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 +
238 284 ## Raw blob content
239 285  
240 286 Get the raw file contents for a file.
... ... @@ -249,4 +295,10 @@ Parameters:
249 295 + `sha` (required) - The commit or branch name
250 296 + `filepath` (required) - The path the file
251 297  
252   -Will return the raw file contents.
  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 +
... ...
lib/api/projects.rb
  Diff comments   View file @e119b0a
... ... @@ -331,7 +331,9 @@ module Gitlab
331 331 #
332 332 # Parameters:
333 333 # id (required) - The ID of a project
334   - # ref_name (optional) - The name of a repository branch or tag
  334 + # ref_name (optional) - The name of a repository branch or tag, if not given the default branch is used
  335 + # page (optional) - The page number of the commit pagination
  336 + # per_page (optional) - The number of elements per page used in pagination
335 337 # Example Request:
336 338 # GET /projects/:id/repository/commits
337 339 get ":id/repository/commits" do
... ...
spec/requests/api/projects_spec.rb
  Diff comments   View file @e119b0a
... ... @@ -433,14 +433,19 @@ describe Gitlab::API do
433 433 end
434 434  
435 435 it "should return success when deleting hook" do
436   - delete api("/projects/#{project.id}/hooks/#{hook.id}", user)
  436 + delete api("/projects/#{project.id}/hooks", user), hook_id: hook.id
437 437 response.status.should == 200
438 438 end
439 439  
440 440 it "should return success when deleting non existent hook" do
441   - delete api("/projects/#{project.id}/hooks/42", user)
  441 + delete api("/projects/#{project.id}/hooks", user), hook_id: 42
442 442 response.status.should == 200
443 443 end
  444 +
  445 + it "should return a 400 error if hook id not given" do
  446 + delete api("/projects/#{project.id}/hooks", user)
  447 + response.status.should == 400
  448 + end
444 449 end
445 450  
446 451 describe "GET /projects/:id/repository/tags" do
... ... @@ -480,11 +485,6 @@ describe Gitlab::API do
480 485 json_response.should be_an Array
481 486 json_response.first['title'].should == snippet.title
482 487 end
483   -
484   - it "should return 401 error if user not authenticated" do
485   - get api("/projects/#{project.id}/snippets")
486   - response.status.should == 401
487   - end
488 488 end
489 489  
490 490 describe "GET /projects/:id/snippets/:snippet_id" do
... ... @@ -525,12 +525,6 @@ describe Gitlab::API do
525 525 title: 'api test', file_name: 'sample.rb'
526 526 response.status.should == 400
527 527 end
528   -
529   - it "should return a 401 error if user not authenticated" do
530   - post api("/projects/#{project.id}/snippets"),
531   - title: 'api test', file_name: 'sample.rb', code: 'i=0'
532   - response.status.should == 401
533   - end
534 528 end
535 529  
536 530 describe "PUT /projects/:id/snippets/:shippet_id" do
... ...