API: issues documentation and API functions updated

The issues documentation is updated with infos to status codes and the deprecated `DELETE` function and
how to close an issue. A few more tests added to check status codes of API functions.

3 files changed, 77 insertions, 7 deletions

diff --git a/doc/api/issues.md b/doc/api/issues.md
index 0383b676073..b782cec975b 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -1,6 +1,7 @@
 ## List issues
 
-Get all issues created by authenticed user.
+Get all issues created by authenticed user. This function takes pagination parameters
+`page` and `per_page` to get a list of issues.
 
 ```
 GET /issues
@@ -68,9 +69,18 @@ GET /issues
 ]
 ```
 
+Return values:
+
++ `200 Ok` on success and the list of issues
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if something fails
+
+
+
 ## List project issues
 
-Get a list of project issues.
+Get a list of project issues. This function accepts pagination parameters `page` and `per_page`
+to return the list of project issues.
 
 ```
 GET /projects/:id/issues
@@ -80,9 +90,16 @@ Parameters:
 
 + `id` (required) - The ID of a project
 
+Return values:
+
++ `200 Ok` on success and the list of project issues
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID not found
+
+
 ## Single issue
 
-Get a project issue.
+Gets a single project issue.
 
 ```
 GET /projects/:id/issues/:issue_id
@@ -133,9 +150,16 @@ Parameters:
 }
 ```
 
+Return values:
+
++ `200 Ok` on success and the list of project issues
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or issue ID not found
+
+
 ## New issue
 
-Create a new project issue.
+Creates a new project issue.
 
 ```
 POST /projects/:id/issues
@@ -150,11 +174,17 @@ Parameters:
 + `milestone_id` (optional) - The ID of a milestone to assign issue
 + `labels` (optional) - Comma-separated label names for an issue
 
-Will return created issue with status `201 Created` on success, or `404 Not found` on fail.
+Return values:
+
++ `201 Created` on success and the newly created project issue
++ `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 issue
 
-Update an existing project issue.
+Updates an existing project issue. This function is also used to mark an issue as closed.
 
 ```
 PUT /projects/:id/issues/:issue_id
@@ -171,5 +201,28 @@ Parameters:
 + `labels` (optional) - Comma-separated label names for an issue
 + `closed` (optional) - The state of an issue (0 = false, 1 = true)
 
-Will return updated issue with status `200 OK` on success, or `404 Not found` on fail.
+Return values:
+
++ `200 Ok` on success and the update project issue
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or issue ID not found
+
+
+## Delete existing issue (**Deprecated**)
+
+The function is deprecated and returns a `405 Method Not Allowed`
+error if called. An issue gets now closed and is done by calling `PUT /projects/:id/issues/:issue_id` with
+parameter `closed` set to 1.
+
+```
+DELETE /projects/:id/issues/:issue_id
+```
+
+Parameters:
+
++ `id` (required) - The project ID
++ `issue_id` (required) - The ID of the issue
+
+Return values:
 
++ `405 Method Not Allowed` is always returned, because the function is deprecated
diff --git a/lib/api/issues.rb b/lib/api/issues.rb
index 70bbf47e72c..da966fc0399 100644
--- a/lib/api/issues.rb
+++ b/lib/api/issues.rb
@@ -48,6 +48,7 @@ module Gitlab
       # Example Request:
       #   POST /projects/:id/issues
       post ":id/issues" do
+        bad_request!(:title) unless params[:title].present?
         attrs = attributes_for_keys [:title, :description, :assignee_id, :milestone_id]
         attrs[:label_list] = params[:labels] if params[:labels].present?
         @issue = user_project.issues.new attrs
diff --git a/spec/requests/api/issues_spec.rb b/spec/requests/api/issues_spec.rb
index 630ac0f820a..ecf0bdb7084 100644
--- a/spec/requests/api/issues_spec.rb
+++ b/spec/requests/api/issues_spec.rb
@@ -41,6 +41,11 @@ describe Gitlab::API do
       response.status.should == 200
       json_response['title'].should == issue.title
     end
+
+    it "should return 404 if issue id not found" do
+      get api("/projects/#{project.id}/issues/54321", user)
+      response.status.should == 404
+    end
   end
 
   describe "POST /projects/:id/issues" do
@@ -52,6 +57,11 @@ describe Gitlab::API do
       json_response['description'].should be_nil
       json_response['labels'].should == ['label', 'label2']
     end
+
+    it "should return a 400 bad request if title not given" do
+      post api("/projects/#{project.id}/issues", user), labels: 'label, label2'
+      response.status.should == 400
+    end
   end
 
   describe "PUT /projects/:id/issues/:issue_id to update only title" do
@@ -62,6 +72,12 @@ describe Gitlab::API do
 
       json_response['title'].should == 'updated title'
     end
+
+    it "should return 404 error if issue id not found" do
+      put api("/projects/#{project.id}/issues/44444", user),
+        title: 'updated title'
+      response.status.should == 404
+    end
   end
 
   describe "PUT /projects/:id/issues/:issue_id to update state and label" do