deac
/
gitlabhq
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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.
5-0-stable
Sebastian Ziebell 2013-02-20 22:17:05 +01:00
parent f0e417091c
commit 33c1463645
3 changed files with 241 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

269
doc/api/notes.md
View File

@ -1,4 +1,4 @@
## List notes
## Wall
### List project wall notes
@ -30,50 +30,15 @@ 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 /projects/:id/merge_requests/:merge_request_id/notes
```
Parameters:
### Get single wall note
+ `id` (required) - The ID of a project
+ `merge_request_id` (required) - The ID of an merge request
### List issue notes
Get a list of issue notes.
```
GET /projects/:id/issues/:issue_id/notes
```
Parameters:
+ `id` (required) - The ID of a project
+ `issue_id` (required) - The ID of an issue
### List snippet notes
Get a list of snippet notes.
```
GET /projects/:id/snippets/:snippet_id/notes
```
Parameters:
+ `id` (required) - The ID of a project
+ `snippet_id` (required) - The ID of a snippet
## Single note
### Single wall note
Get a wall note.
Returns a single wall note.
```
GET /projects/:id/notes/:note_id
@ -84,9 +49,60 @@ Parameters:
+ `id` (required) - The ID of a project
+ `note_id` (required) - The ID of a wall note
### Single issue note
Return values:
Get an issue note.
+ `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
```
Parameters:
+ `id` (required) - The ID of a project
+ `issue_id` (required) - The ID of an issue
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 single issue note
Returns a single note for a specific project issue
```
GET /projects/:id/issues/:issue_id/notes/:note_id
@ -98,41 +114,16 @@ Parameters:
+ `issue_id` (required) - The ID of a project issue
+ `note_id` (required) - The ID of an issue note
### Single snippet note
Return values:
Get a snippet note.
```
GET /projects/:id/issues/:snippet_id/notes/:note_id
```
Parameters:
+ `id` (required) - The ID of a project
+ `snippet_id` (required) - The ID of a project snippet
+ `note_id` (required) - The ID of an snippet note
## New note
### New wall note
Create a new wall note.
```
POST /projects/:id/notes
```
Parameters:
+ `id` (required) - The ID of a project
+ `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.
+ `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
### New issue note
### Create new issue note
Create a new issue note.
Creates a new note to a single project issue.
```
POST /projects/:id/issues/:issue_id/notes
@ -144,11 +135,61 @@ Parameters:
+ `issue_id` (required) - The ID of an issue
+ `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:
### New snippet note
+ `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
Create a new snippet 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/snippets/:snippet_id/notes
```
Parameters:
+ `id` (required) - The ID of a project
+ `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
### Get single snippet note
Returns a single note for a given snippet.
```
GET /projects/:id/snippets/:snippet_id/notes/:note_id
```
Parameters:
+ `id` (required) - The ID of a project
+ `snippet_id` (required) - The ID of a project snippet
+ `note_id` (required) - The ID of an snippet note
Return values:
+ `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 new snippet note
Creates a new note for a single snippet. Snippet notes are comments users can post to a snippet.
```
POST /projects/:id/snippets/:snippet_id/notes
@ -160,4 +201,76 @@ Parameters:
+ `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
## Merge Requests
### List all merge request notes
Gets a list of all notes for a single merge request.
```
GET /projects/:id/merge_requests/:merge_request_id/notes
```
Parameters:
+ `id` (required) - The ID of a project
+ `merge_request_id` (required) - The ID of a project merge request
Return values:
+ `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
### Get single merge request note
Returns a single note for a given merge request.
```
GET /projects/:id/merge_requests/:merge_request_id/notes/:note_id
```
Parameters:
+ `id` (required) - The ID of a project
+ `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
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

5
lib/api/notes.rb
View File

@ -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

46
spec/requests/api/notes_spec.rb
View File

@ -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