Commit 4a60c377 authored by Sebastian Ziebell's avatar Sebastian Ziebell

API documentation update for milestones

Updated the milestones API documentation and added return codes descriptions.
parent 33c14636
## List project milestones ## List project milestones
Get a list of project milestones. Returns a list of project milestones.
``` ```
GET /projects/:id/milestones GET /projects/:id/milestones
...@@ -10,9 +10,16 @@ Parameters: ...@@ -10,9 +10,16 @@ Parameters:
+ `id` (required) - The ID of a project + `id` (required) - The ID of a project
## Single milestone Return values:
Get a single project milestone. + `200 Ok` on success and the list of project milestones
+ `401 Unauthorized` if user is not authenticated
+ `404 Not Found` if project ID not found
## Get single milestone
Gets a single project milestone.
``` ```
GET /projects/:id/milestones/:milestone_id GET /projects/:id/milestones/:milestone_id
...@@ -23,9 +30,16 @@ Parameters: ...@@ -23,9 +30,16 @@ Parameters:
+ `id` (required) - The ID of a project + `id` (required) - The ID of a project
+ `milestone_id` (required) - The ID of a project milestone + `milestone_id` (required) - The ID of a project milestone
## New milestone Return values:
+ `200 Ok` on success and the single milestone
+ `401 Unauthorized` if user is not authenticated
+ `404 Not Found` if project ID not found
## Create new milestone
Create a new project milestone. Creates a new project milestone.
``` ```
POST /projects/:id/milestones POST /projects/:id/milestones
...@@ -38,9 +52,17 @@ Parameters: ...@@ -38,9 +52,17 @@ Parameters:
+ `description` (optional) - The description of the milestone + `description` (optional) - The description of the milestone
+ `due_date` (optional) - The due date of the milestone + `due_date` (optional) - The due date of the milestone
Return values:
+ `201 Created` on success and the new milestone
+ `400 Bad Request` if the required attribute title is not given
+ `401 Unauthorized` if user is not authenticated
+ `404 Not Found` if project ID not found
## Edit milestone ## Edit milestone
Update an existing project milestone. Updates an existing project milestone.
``` ```
PUT /projects/:id/milestones/:milestone_id PUT /projects/:id/milestones/:milestone_id
...@@ -54,3 +76,9 @@ Parameters: ...@@ -54,3 +76,9 @@ Parameters:
+ `description` (optional) - The description of a milestone + `description` (optional) - The description of a milestone
+ `due_date` (optional) - The due date of the milestone + `due_date` (optional) - The due date of the milestone
+ `closed` (optional) - The status of the milestone + `closed` (optional) - The status of the milestone
Return values:
+ `200 Ok` on success and the updated milestone
+ `401 Unauthorized` if user is not authenticated
+ `404 Not Found` if project ID or milestone ID not found
...@@ -4,20 +4,6 @@ module Gitlab ...@@ -4,20 +4,6 @@ module Gitlab
before { authenticate! } before { authenticate! }
resource :projects do resource :projects do
helpers do
# If an error occurs this helper method handles error codes for a given milestone
#
# Parameters:
# milestone_errors (required) - The erros collection of a milestone
#
def handle_milestone_errors(milestone_errors)
if milestone_errors[:title].any?
bad_request!(:title)
end
end
end
# Get a list of project milestones # Get a list of project milestones
# #
# Parameters: # Parameters:
...@@ -56,12 +42,13 @@ module Gitlab ...@@ -56,12 +42,13 @@ module Gitlab
post ":id/milestones" do post ":id/milestones" do
authorize! :admin_milestone, user_project authorize! :admin_milestone, user_project
bad_request!(:title) unless params[:title].present?
attrs = attributes_for_keys [:title, :description, :due_date] attrs = attributes_for_keys [:title, :description, :due_date]
@milestone = user_project.milestones.new attrs @milestone = user_project.milestones.new attrs
if @milestone.save if @milestone.save
present @milestone, with: Entities::Milestone present @milestone, with: Entities::Milestone
else else
handle_milestone_errors(@milestone.errors)
not_found! not_found!
end end
end end
...@@ -85,7 +72,6 @@ module Gitlab ...@@ -85,7 +72,6 @@ module Gitlab
if @milestone.update_attributes attrs if @milestone.update_attributes attrs
present @milestone, with: Entities::Milestone present @milestone, with: Entities::Milestone
else else
handle_milestone_errors(@milestone.errors)
not_found! not_found!
end end
end end
......
...@@ -16,6 +16,11 @@ describe Gitlab::API do ...@@ -16,6 +16,11 @@ describe Gitlab::API do
json_response.should be_an Array json_response.should be_an Array
json_response.first['title'].should == milestone.title json_response.first['title'].should == milestone.title
end end
it "should return a 401 error if user not authenticated" do
get api("/projects/#{project.id}/milestones")
response.status.should == 401
end
end end
describe "GET /projects/:id/milestones/:milestone_id" do describe "GET /projects/:id/milestones/:milestone_id" do
...@@ -25,6 +30,11 @@ describe Gitlab::API do ...@@ -25,6 +30,11 @@ describe Gitlab::API do
json_response['title'].should == milestone.title json_response['title'].should == milestone.title
end end
it "should return 401 error if user not authenticated" do
get api("/projects/#{project.id}/milestones/#{milestone.id}")
response.status.should == 401
end
it "should return a 404 error if milestone id not found" do it "should return a 404 error if milestone id not found" do
get api("/projects/#{project.id}/milestones/1234", user) get api("/projects/#{project.id}/milestones/1234", user)
response.status.should == 404 response.status.should == 404
...@@ -33,8 +43,7 @@ describe Gitlab::API do ...@@ -33,8 +43,7 @@ describe Gitlab::API do
describe "POST /projects/:id/milestones" do describe "POST /projects/:id/milestones" do
it "should create a new project milestone" do it "should create a new project milestone" do
post api("/projects/#{project.id}/milestones", user), post api("/projects/#{project.id}/milestones", user), title: 'new milestone'
title: 'new milestone'
response.status.should == 201 response.status.should == 201
json_response['title'].should == 'new milestone' json_response['title'].should == 'new milestone'
json_response['description'].should be_nil json_response['description'].should be_nil
...@@ -62,7 +71,7 @@ describe Gitlab::API do ...@@ -62,7 +71,7 @@ describe Gitlab::API do
json_response['title'].should == 'updated title' json_response['title'].should == 'updated title'
end end
it "should return a 404 error if milestone is not found" do it "should return a 404 error if milestone id not found" do
put api("/projects/#{project.id}/milestones/1234", user), put api("/projects/#{project.id}/milestones/1234", user),
title: 'updated title' title: 'updated title'
response.status.should == 404 response.status.should == 404
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment