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.

3 files changed, 73 insertions, 25 deletions

diff --git a/doc/api/repositories.md b/doc/api/repositories.md
index fd0ef1f53eb..17346278f79 100644
--- a/doc/api/repositories.md
+++ b/doc/api/repositories.md
@@ -1,4 +1,4 @@
-## Project repository branches
+## List repository branches
 
 Get a list of repository branches from a project, sorted by name alphabetically.
 
@@ -39,7 +39,14 @@ Parameters:
 ]
 ```
 
-## Project repository branch
+Return values:
+
++ `200 Ok`on success and a list of repository branches for the project
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project with ID not found
+
+
+## Get single repository branch
 
 Get a single project repository branch.
 
@@ -79,12 +86,18 @@ Parameters:
 }
 ```
 
-Will return status code `200` on success or `404 Not found` if the branch is not available.
+Return values:
 
++ `200 Ok` on success and the repository branch
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if the project ID or branch not found
 
-## Protect a project repository branch
 
-Protect a single project repository branch.
+
+## Protect repository branch
+
+Protects a single project repository branch. This is an idempotent function, protecting an already
+protected repository branch still returns a `200 Ok` status code.
 
 ```
 PUT /projects/:id/repository/branches/:branch/protect
@@ -122,9 +135,18 @@ Parameters:
 }
 ```
 
-## Unprotect a project repository branch
+Return values:
+
++ `200 Ok` on success and the updated repository branch
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if the the project ID or branch not found
 
-Unprotect a single project repository branch.
+
+
+## Unprotect repository branch
+
+Unprotects a single project repository branch. This is an idempotent function, unprotecting an already
+unprotected repository branch still returns a `200 Ok` status code.
 
 ```
 PUT /projects/:id/repository/branches/:branch/unprotect
@@ -162,7 +184,15 @@ Parameters:
 }
 ```
 
-## Project repository tags
+Return values:
+
++ `200 Ok` on success and the updated repository branch
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if the project ID or the branch not found
+
+
+
+## List project repository tags
 
 Get a list of repository tags from a project, sorted by name in reverse alphabetical order.
 
@@ -201,7 +231,14 @@ Parameters:
 ]
 ```
 
-## Project repository commits
+Return values:
+
++ `200 Ok` on success and the list of repository tags
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if the project ID not found
+
+
+## List repository commits
 
 Get a list of repository commits in a project.
 
@@ -212,7 +249,9 @@ GET /projects/:id/repository/commits
 Parameters:
 
 + `id` (required) - The ID of a project
-+ `ref_name` (optional) - The name of a repository branch or tag
++ `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch
++ `page`(optional) - The page with the commits (pagination)
++ `per_page` (optional) - The number of commits per page (pagination)
 
 ```json
 [
@@ -235,6 +274,13 @@ Parameters:
 ]
 ```
 
+Return values:
+
++ `200 Ok` on success and a list of commits
++ `401 Unauthorized` if the user is not authenticated
++ `404 Not Found` if the project ID not found
+
+
 ## Raw blob content
 
 Get the raw file contents for a file.
@@ -249,4 +295,10 @@ Parameters:
 + `sha` (required) - The commit or branch name
 + `filepath` (required) - The path the file
 
-Will return the raw file contents.
+Return values:
+
++ `200 Ok` on success and the raw content of the file
++ `400 Bad Request` if required attribute filepath is not given
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or sha commit or branch name not found
+
diff --git a/lib/api/projects.rb b/lib/api/projects.rb
index 65381dac6ac..c749c24f228 100644
--- a/lib/api/projects.rb
+++ b/lib/api/projects.rb
@@ -331,7 +331,9 @@ module Gitlab
       #
       # Parameters:
       #   id (required) - The ID of a project
-      #   ref_name (optional) - The name of a repository branch or tag
+      #   ref_name (optional) - The name of a repository branch or tag, if not given the default branch is used
+      #   page (optional) - The page number of the commit pagination
+      #   per_page (optional) - The number of elements per page used in pagination
       # Example Request:
       #   GET /projects/:id/repository/commits
       get ":id/repository/commits" do
diff --git a/spec/requests/api/projects_spec.rb b/spec/requests/api/projects_spec.rb
index 8ab7d825a20..9fbdd52eefc 100644
--- a/spec/requests/api/projects_spec.rb
+++ b/spec/requests/api/projects_spec.rb
@@ -433,14 +433,19 @@ describe Gitlab::API do
     end
 
     it "should return success when deleting hook" do
-      delete api("/projects/#{project.id}/hooks/#{hook.id}", user)
+      delete api("/projects/#{project.id}/hooks", user), hook_id: hook.id
       response.status.should == 200
     end
 
     it "should return success when deleting non existent hook" do
-      delete api("/projects/#{project.id}/hooks/42", user)
+      delete api("/projects/#{project.id}/hooks", user), hook_id: 42
       response.status.should == 200
     end
+
+    it "should return a 400 error if hook id not given" do
+      delete api("/projects/#{project.id}/hooks", user)
+      response.status.should == 400
+    end
   end
 
   describe "GET /projects/:id/repository/tags" do
@@ -480,11 +485,6 @@ describe Gitlab::API do
       json_response.should be_an Array
       json_response.first['title'].should == snippet.title
     end
-
-    it "should return 401 error if user not authenticated" do
-      get api("/projects/#{project.id}/snippets")
-      response.status.should == 401
-    end
   end
 
   describe "GET /projects/:id/snippets/:snippet_id" do
@@ -525,12 +525,6 @@ describe Gitlab::API do
         title: 'api test', file_name: 'sample.rb'
       response.status.should == 400
     end
-
-    it "should return a 401 error if user not authenticated" do
-      post api("/projects/#{project.id}/snippets"),
-        title: 'api test', file_name: 'sample.rb', code: 'i=0'
-      response.status.should == 401
-    end
   end
 
   describe "PUT /projects/:id/snippets/:shippet_id" do