From e119b0a0cb33b1b7f2dafcf17c2a94af40aed833 Mon Sep 17 00:00:00 2001 From: Sebastian Ziebell Date: Wed, 27 Feb 2013 11:24:12 +0100 Subject: [PATCH] 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. --- doc/api/repositories.md | 74 +++++++++++++++++++++++++----- lib/api/projects.rb | 4 +- spec/requests/api/projects_spec.rb | 20 +++----- 3 files changed, 73 insertions(+), 25 deletions(-) diff --git a/doc/api/repositories.md b/doc/api/repositories.md index fd0ef1f5..17346278 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: -Unprotect a single project repository branch. ++ `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 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 65381dac..c749c24f 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 8ab7d825..9fbdd52e 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