API: fixes return codes for notes, documentation updated

The notes API documentation updated with return codes. API now returns `400 Bad Request` if
required attributes are not present. Return codes are documented now, also tested in added tests.
The documentation now reflects the current state of the API.

3 files changed, 203 insertions, 41 deletions

diff --git a/doc/api/notes.md b/doc/api/notes.md
index eef4b63fcaf..6a6a99aa4f4 100644
--- a/doc/api/notes.md
+++ b/doc/api/notes.md
@@ -1,4 +1,4 @@
-## List notes
+## Wall
 
 ### List project wall notes
 
@@ -30,22 +30,59 @@ Parameters:
 
 + `id` (required) - The ID of a project
 
-### List merge request notes
+Return values:
 
-Get a list of merge request notes.
++ `200 Ok` on success and a list of notes
++ `401 Unauthorized` if user is not authorized to access this page
+
+
+### Get single wall note
+
+Returns a single wall note.
 
 ```
-GET /projects/:id/merge_requests/:merge_request_id/notes
+GET /projects/:id/notes/:note_id
 ```
 
 Parameters:
 
 + `id` (required) - The ID of a project
-+ `merge_request_id` (required) - The ID of an merge request
++ `note_id` (required) - The ID of a wall note
 
-### List issue notes
+Return values:
 
-Get a list of issue notes.
++ `200 Ok` on success and the wall note (see example at `GET /projects/:id/notes`)
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if note ID not found
+
+
+### Create new wall note
+
+Creates a new wall note.
+
+```
+POST /projects/:id/notes
+```
+
+Parameters:
+
++ `id` (required) - The ID of a project
++ `body` (required) - The content of a note
+
+Return values:
+
++ `201 Created` on success and the new wall note
++ `400 Bad Request` if attribute body is not given
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if something else fails
+
+
+
+## Issues
+
+### List project issue notes
+
+Gets a list of all notes for a single issue.
 
 ```
 GET /projects/:id/issues/:issue_id/notes
@@ -56,54 +93,85 @@ Parameters:
 + `id` (required) - The ID of a project
 + `issue_id` (required) - The ID of an issue
 
-### List snippet notes
+Return values:
+
++ `200 Ok` on success and a list of notes for a single issue
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or issue ID not found
 
-Get a list of snippet notes.
+
+### Get single issue note
+
+Returns a single note for a specific project issue
 
 ```
-GET /projects/:id/snippets/:snippet_id/notes
+GET /projects/:id/issues/:issue_id/notes/:note_id
 ```
 
 Parameters:
 
 + `id` (required) - The ID of a project
-+ `snippet_id` (required) - The ID of a snippet
++ `issue_id` (required) - The ID of a project issue
++ `note_id` (required) - The ID of an issue note
+
+Return values:
+
++ `200 Ok` on success and the single issue note
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID, issue ID or note ID is not found
 
-## Single note
 
-### Single wall note
+### Create new issue note
 
-Get a wall note.
+Creates a new note to a single project issue.
 
 ```
-GET /projects/:id/notes/:note_id
+POST /projects/:id/issues/:issue_id/notes
 ```
 
 Parameters:
 
 + `id` (required) - The ID of a project
-+ `note_id` (required) - The ID of a wall note
++ `issue_id` (required) - The ID of an issue
++ `body` (required) - The content of a note
+
+Return values:
+
++ `201 Created` on succes and the created note
++ `400 Bad Request` if the required attribute body is not given
++ `401 Unauthorized` if the user is not authenticated
++ `404 Not Found` if the project ID or the issue ID not found
 
-### Single issue note
 
-Get an issue note.
+
+## Snippets
+
+### List all snippet notes
+
+Gets a list of all notes for a single snippet. Snippet notes are comments users can post to a snippet.
 
 ```
-GET /projects/:id/issues/:issue_id/notes/:note_id
+GET /projects/:id/snippets/:snippet_id/notes
 ```
 
 Parameters:
 
 + `id` (required) - The ID of a project
-+ `issue_id` (required) - The ID of a project issue
-+ `note_id` (required) - The ID of an issue note
++ `snippet_id` (required) - The ID of a project snippet
+
+Return values:
+
++ `200 Ok` on success and a list of notes for a single snippet
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or issue ID not found
+
 
-### Single snippet note
+### Get single snippet note
 
-Get a snippet note.
+Returns a single note for a given snippet.
 
 ```
-GET /projects/:id/issues/:snippet_id/notes/:note_id
+GET /projects/:id/snippets/:snippet_id/notes/:note_id
 ```
 
 Parameters:
@@ -112,52 +180,97 @@ Parameters:
 + `snippet_id` (required) - The ID of a project snippet
 + `note_id` (required) - The ID of an snippet note
 
-## New note
+Return values:
 
-### New wall note
++ `200 Ok` on success and the single snippet note
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID, snippet ID or note ID is not found
 
-Create a new wall note.
+
+### Create new snippet note
+
+Creates a new note for a single snippet. Snippet notes are comments users can post to a snippet.
 
 ```
-POST /projects/:id/notes
+POST /projects/:id/snippets/:snippet_id/notes
 ```
 
 Parameters:
 
 + `id` (required) - The ID of a project
++ `snippet_id` (required) - The ID of an snippet
 + `body` (required) - The content of a note
 
-Will return created note with status `201 Created` on success, `400 Bad Request` if the body attribute is missing or `404 Not found` on fail.
+Return values:
 
++ `201 Created` on success and the new snippet note
++ `400 Bad Request` if the required attribute body not given
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or snippet ID not found
 
-### New issue note
 
-Create a new issue note.
+
+## Merge Requests
+
+### List all merge request notes
+
+Gets a list of all notes for a single merge request.
 
 ```
-POST /projects/:id/issues/:issue_id/notes
+GET /projects/:id/merge_requests/:merge_request_id/notes
 ```
 
 Parameters:
 
 + `id` (required) - The ID of a project
-+ `issue_id` (required) - The ID of an issue
-+ `body` (required) - The content of a note
++ `merge_request_id` (required) - The ID of a project merge request
+
+Return values:
 
-Will return created note with status `201 Created` on success, `400 Bad Request` if the body attribute is missing or `404 Not found` on fail.
++ `200 Ok` on success and a list of notes for a single merge request
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or merge request ID not found
 
-### New snippet note
 
-Create a new snippet note.
+### Get single merge request note
+
+Returns a single note for a given merge request.
 
 ```
-POST /projects/:id/snippets/:snippet_id/notes
+GET /projects/:id/merge_requests/:merge_request_id/notes/:note_id
 ```
 
 Parameters:
 
 + `id` (required) - The ID of a project
-+ `snippet_id` (required) - The ID of an snippet
++ `merge_request_id` (required) - The ID of a project merge request
++ `note_id` (required) - The ID of a merge request note
+
+Return values:
+
++ `200 Ok` on success and the single merge request note
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID, merge request ID or note ID is not found
+
+
+### Create new merge request note
+
+Creates a new note for a single merge request.
+
+```
+POST /projects/:id/merge_requests/:merge_request_id/notes
+```
+
+Parameters:
+
++ `id` (required) - The ID of a project
++ `merge_request_id` (required) - The ID of a merge request
 + `body` (required) - The content of a note
 
-Will return created note with status `201 Created` on success, `400 Bad Request` if the body attribute is missing or `404 Not found` on fail.
+Return values:
+
++ `201 Created` on success and the new merge request note
++ `400 Bad Request` if the required attribute body not given
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or merge request ID not found
+
diff --git a/lib/api/notes.rb b/lib/api/notes.rb
index 56de6e090e5..953514b6f04 100644
--- a/lib/api/notes.rb
+++ b/lib/api/notes.rb
@@ -37,6 +37,8 @@ module Gitlab
       # Example Request:
       #   POST /projects/:id/notes
       post ":id/notes" do
+        bad_request!(:body) unless params[:body].present?
+
         @note = user_project.notes.new(note: params[:body])
         @note.author = current_user
 
@@ -91,6 +93,9 @@ module Gitlab
         #   POST /projects/:id/issues/:noteable_id/notes
         #   POST /projects/:id/snippets/:noteable_id/notes
         post ":id/#{noteables_str}/:#{noteable_id_str}/notes" do
+          bad_request!(:"#{noteable_id_str}") unless params[:"#{noteable_id_str}"].present?
+          bad_request!(:body) unless params[:body].present?
+
           @noteable = user_project.send(:"#{noteables_str}").find(params[:"#{noteable_id_str}"])
           @note = @noteable.notes.new(note: params[:body])
           @note.author = current_user
diff --git a/spec/requests/api/notes_spec.rb b/spec/requests/api/notes_spec.rb
index d382d7d9294..92ac5befc3a 100644
--- a/spec/requests/api/notes_spec.rb
+++ b/spec/requests/api/notes_spec.rb
@@ -52,7 +52,12 @@ describe Gitlab::API do
       json_response['body'].should == 'hi!'
     end
 
-    it "should return a 400 error if body is missing" do
+    it "should return 401 unauthorized error" do
+      post api("/projects/#{project.id}/notes")
+      response.status.should == 401
+    end
+
+    it "should return a 400 bad request if body is missing" do
       post api("/projects/#{project.id}/notes", user)
       response.status.should == 400
     end
@@ -94,6 +99,18 @@ describe Gitlab::API do
         json_response.should be_an Array
         json_response.first['body'].should == merge_request_note.note
       end
+
+      it "should return a 404 error if merge request id not found" do
+        get api("/projects/#{project.id}/merge_requests/4444/notes", user)
+        response.status.should == 404
+      end
+    end
+
+    context "when notable is invalid" do
+      it "should return a 404 error" do
+        get api("/projects/#{project.id}/unknown/#{snippet.id}/notes", user)
+        response.status.should == 404
+      end
     end
   end
 
@@ -133,6 +150,16 @@ describe Gitlab::API do
         json_response['body'].should == 'hi!'
         json_response['author']['email'].should == user.email
       end
+
+      it "should return a 400 bad request error if body not given" do
+        post api("/projects/#{project.id}/issues/#{issue.id}/notes", user)
+        response.status.should == 400
+      end
+
+      it "should return a 401 unauthorized error if user not authenticated" do
+        post api("/projects/#{project.id}/issues/#{issue.id}/notes"), body: 'hi!'
+        response.status.should == 401
+      end
     end
 
     context "when noteable is a Snippet" do
@@ -142,6 +169,23 @@ describe Gitlab::API do
         json_response['body'].should == 'hi!'
         json_response['author']['email'].should == user.email
       end
+
+      it "should return a 400 bad request error if body not given" do
+        post api("/projects/#{project.id}/snippets/#{snippet.id}/notes", user)
+        response.status.should == 400
+      end
+
+      it "should return a 401 unauthorized error if user not authenticated" do
+        post api("/projects/#{project.id}/snippets/#{snippet.id}/notes"), body: 'hi!'
+        response.status.should == 401
+      end
+    end
+
+    context "when noteable is invalid" do
+      it "should return a 404 error" do
+        post api("/projects/#{project.id}/invalid/#{snippet.id}/notes", user)
+        response.status.should == 404
+      end
     end
   end
 end