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.

1 files changed, 153 insertions, 40 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
+