Download as
Browse Code »

Commit 33c1463645b51bcb26932e4825df0ce8fee6c729

Authored by Sebastian Ziebell
1 parent f0e41709
Exists in master and in 4 other branches 6-8-stable, 7-0-stable, 7-0-stable-spb, spb-stable

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.
Showing 3 changed files with 203 additions and 41 deletions   Show diff stats
doc/api/notes.md
  Diff comments   View file @33c1463
1   -## List notes
  1 +## Wall
2 2  
3 3 ### List project wall notes
4 4  
... ... @@ -30,22 +30,59 @@ Parameters:
30 30  
31 31 + `id` (required) - The ID of a project
32 32  
33   -### List merge request notes
  33 +Return values:
34 34  
35   -Get a list of merge request notes.
  35 ++ `200 Ok` on success and a list of notes
  36 ++ `401 Unauthorized` if user is not authorized to access this page
  37 +
  38 +
  39 +### Get single wall note
  40 +
  41 +Returns a single wall note.
36 42  
37 43 ```
38   -GET /projects/:id/merge_requests/:merge_request_id/notes
  44 +GET /projects/:id/notes/:note_id
39 45 ```
40 46  
41 47 Parameters:
42 48  
43 49 + `id` (required) - The ID of a project
44   -+ `merge_request_id` (required) - The ID of an merge request
  50 ++ `note_id` (required) - The ID of a wall note
45 51  
46   -### List issue notes
  52 +Return values:
47 53  
48   -Get a list of issue notes.
  54 ++ `200 Ok` on success and the wall note (see example at `GET /projects/:id/notes`)
  55 ++ `401 Unauthorized` if user is not authenticated
  56 ++ `404 Not Found` if note ID not found
  57 +
  58 +
  59 +### Create new wall note
  60 +
  61 +Creates a new wall note.
  62 +
  63 +```
  64 +POST /projects/:id/notes
  65 +```
  66 +
  67 +Parameters:
  68 +
  69 ++ `id` (required) - The ID of a project
  70 ++ `body` (required) - The content of a note
  71 +
  72 +Return values:
  73 +
  74 ++ `201 Created` on success and the new wall note
  75 ++ `400 Bad Request` if attribute body is not given
  76 ++ `401 Unauthorized` if user is not authenticated
  77 ++ `404 Not Found` if something else fails
  78 +
  79 +
  80 +
  81 +## Issues
  82 +
  83 +### List project issue notes
  84 +
  85 +Gets a list of all notes for a single issue.
49 86  
50 87 ```
51 88 GET /projects/:id/issues/:issue_id/notes
... ... @@ -56,54 +93,85 @@ Parameters:
56 93 + `id` (required) - The ID of a project
57 94 + `issue_id` (required) - The ID of an issue
58 95  
59   -### List snippet notes
  96 +Return values:
  97 +
  98 ++ `200 Ok` on success and a list of notes for a single issue
  99 ++ `401 Unauthorized` if user is not authenticated
  100 ++ `404 Not Found` if project ID or issue ID not found
60 101  
61   -Get a list of snippet notes.
  102 +
  103 +### Get single issue note
  104 +
  105 +Returns a single note for a specific project issue
62 106  
63 107 ```
64   -GET /projects/:id/snippets/:snippet_id/notes
  108 +GET /projects/:id/issues/:issue_id/notes/:note_id
65 109 ```
66 110  
67 111 Parameters:
68 112  
69 113 + `id` (required) - The ID of a project
70   -+ `snippet_id` (required) - The ID of a snippet
  114 ++ `issue_id` (required) - The ID of a project issue
  115 ++ `note_id` (required) - The ID of an issue note
  116 +
  117 +Return values:
  118 +
  119 ++ `200 Ok` on success and the single issue note
  120 ++ `401 Unauthorized` if user is not authenticated
  121 ++ `404 Not Found` if project ID, issue ID or note ID is not found
71 122  
72   -## Single note
73 123  
74   -### Single wall note
  124 +### Create new issue note
75 125  
76   -Get a wall note.
  126 +Creates a new note to a single project issue.
77 127  
78 128 ```
79   -GET /projects/:id/notes/:note_id
  129 +POST /projects/:id/issues/:issue_id/notes
80 130 ```
81 131  
82 132 Parameters:
83 133  
84 134 + `id` (required) - The ID of a project
85   -+ `note_id` (required) - The ID of a wall note
  135 ++ `issue_id` (required) - The ID of an issue
  136 ++ `body` (required) - The content of a note
  137 +
  138 +Return values:
  139 +
  140 ++ `201 Created` on succes and the created note
  141 ++ `400 Bad Request` if the required attribute body is not given
  142 ++ `401 Unauthorized` if the user is not authenticated
  143 ++ `404 Not Found` if the project ID or the issue ID not found
86 144  
87   -### Single issue note
88 145  
89   -Get an issue note.
  146 +
  147 +## Snippets
  148 +
  149 +### List all snippet notes
  150 +
  151 +Gets a list of all notes for a single snippet. Snippet notes are comments users can post to a snippet.
90 152  
91 153 ```
92   -GET /projects/:id/issues/:issue_id/notes/:note_id
  154 +GET /projects/:id/snippets/:snippet_id/notes
93 155 ```
94 156  
95 157 Parameters:
96 158  
97 159 + `id` (required) - The ID of a project
98   -+ `issue_id` (required) - The ID of a project issue
99   -+ `note_id` (required) - The ID of an issue note
  160 ++ `snippet_id` (required) - The ID of a project snippet
  161 +
  162 +Return values:
  163 +
  164 ++ `200 Ok` on success and a list of notes for a single snippet
  165 ++ `401 Unauthorized` if user is not authenticated
  166 ++ `404 Not Found` if project ID or issue ID not found
  167 +
100 168  
101   -### Single snippet note
  169 +### Get single snippet note
102 170  
103   -Get a snippet note.
  171 +Returns a single note for a given snippet.
104 172  
105 173 ```
106   -GET /projects/:id/issues/:snippet_id/notes/:note_id
  174 +GET /projects/:id/snippets/:snippet_id/notes/:note_id
107 175 ```
108 176  
109 177 Parameters:
... ... @@ -112,52 +180,97 @@ Parameters:
112 180 + `snippet_id` (required) - The ID of a project snippet
113 181 + `note_id` (required) - The ID of an snippet note
114 182  
115   -## New note
  183 +Return values:
116 184  
117   -### New wall note
  185 ++ `200 Ok` on success and the single snippet note
  186 ++ `401 Unauthorized` if user is not authenticated
  187 ++ `404 Not Found` if project ID, snippet ID or note ID is not found
118 188  
119   -Create a new wall note.
  189 +
  190 +### Create new snippet note
  191 +
  192 +Creates a new note for a single snippet. Snippet notes are comments users can post to a snippet.
120 193  
121 194 ```
122   -POST /projects/:id/notes
  195 +POST /projects/:id/snippets/:snippet_id/notes
123 196 ```
124 197  
125 198 Parameters:
126 199  
127 200 + `id` (required) - The ID of a project
  201 ++ `snippet_id` (required) - The ID of an snippet
128 202 + `body` (required) - The content of a note
129 203  
130   -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.
  204 +Return values:
131 205  
  206 ++ `201 Created` on success and the new snippet note
  207 ++ `400 Bad Request` if the required attribute body not given
  208 ++ `401 Unauthorized` if user is not authenticated
  209 ++ `404 Not Found` if project ID or snippet ID not found
132 210  
133   -### New issue note
134 211  
135   -Create a new issue note.
  212 +
  213 +## Merge Requests
  214 +
  215 +### List all merge request notes
  216 +
  217 +Gets a list of all notes for a single merge request.
136 218  
137 219 ```
138   -POST /projects/:id/issues/:issue_id/notes
  220 +GET /projects/:id/merge_requests/:merge_request_id/notes
139 221 ```
140 222  
141 223 Parameters:
142 224  
143 225 + `id` (required) - The ID of a project
144   -+ `issue_id` (required) - The ID of an issue
145   -+ `body` (required) - The content of a note
  226 ++ `merge_request_id` (required) - The ID of a project merge request
  227 +
  228 +Return values:
146 229  
147   -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.
  230 ++ `200 Ok` on success and a list of notes for a single merge request
  231 ++ `401 Unauthorized` if user is not authenticated
  232 ++ `404 Not Found` if project ID or merge request ID not found
148 233  
149   -### New snippet note
150 234  
151   -Create a new snippet note.
  235 +### Get single merge request note
  236 +
  237 +Returns a single note for a given merge request.
152 238  
153 239 ```
154   -POST /projects/:id/snippets/:snippet_id/notes
  240 +GET /projects/:id/merge_requests/:merge_request_id/notes/:note_id
155 241 ```
156 242  
157 243 Parameters:
158 244  
159 245 + `id` (required) - The ID of a project
160   -+ `snippet_id` (required) - The ID of an snippet
  246 ++ `merge_request_id` (required) - The ID of a project merge request
  247 ++ `note_id` (required) - The ID of a merge request note
  248 +
  249 +Return values:
  250 +
  251 ++ `200 Ok` on success and the single merge request note
  252 ++ `401 Unauthorized` if user is not authenticated
  253 ++ `404 Not Found` if project ID, merge request ID or note ID is not found
  254 +
  255 +
  256 +### Create new merge request note
  257 +
  258 +Creates a new note for a single merge request.
  259 +
  260 +```
  261 +POST /projects/:id/merge_requests/:merge_request_id/notes
  262 +```
  263 +
  264 +Parameters:
  265 +
  266 ++ `id` (required) - The ID of a project
  267 ++ `merge_request_id` (required) - The ID of a merge request
161 268 + `body` (required) - The content of a note
162 269  
163   -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.
  270 +Return values:
  271 +
  272 ++ `201 Created` on success and the new merge request note
  273 ++ `400 Bad Request` if the required attribute body not given
  274 ++ `401 Unauthorized` if user is not authenticated
  275 ++ `404 Not Found` if project ID or merge request ID not found
  276 +
... ...
lib/api/notes.rb
  Diff comments   View file @33c1463
... ... @@ -37,6 +37,8 @@ module Gitlab
37 37 # Example Request:
38 38 # POST /projects/:id/notes
39 39 post ":id/notes" do
  40 + bad_request!(:body) unless params[:body].present?
  41 +
40 42 @note = user_project.notes.new(note: params[:body])
41 43 @note.author = current_user
42 44  
... ... @@ -91,6 +93,9 @@ module Gitlab
91 93 # POST /projects/:id/issues/:noteable_id/notes
92 94 # POST /projects/:id/snippets/:noteable_id/notes
93 95 post ":id/#{noteables_str}/:#{noteable_id_str}/notes" do
  96 + bad_request!(:"#{noteable_id_str}") unless params[:"#{noteable_id_str}"].present?
  97 + bad_request!(:body) unless params[:body].present?
  98 +
94 99 @noteable = user_project.send(:"#{noteables_str}").find(params[:"#{noteable_id_str}"])
95 100 @note = @noteable.notes.new(note: params[:body])
96 101 @note.author = current_user
... ...
spec/requests/api/notes_spec.rb
  Diff comments   View file @33c1463
... ... @@ -52,7 +52,12 @@ describe Gitlab::API do
52 52 json_response['body'].should == 'hi!'
53 53 end
54 54  
55   - it "should return a 400 error if body is missing" do
  55 + it "should return 401 unauthorized error" do
  56 + post api("/projects/#{project.id}/notes")
  57 + response.status.should == 401
  58 + end
  59 +
  60 + it "should return a 400 bad request if body is missing" do
56 61 post api("/projects/#{project.id}/notes", user)
57 62 response.status.should == 400
58 63 end
... ... @@ -94,6 +99,18 @@ describe Gitlab::API do
94 99 json_response.should be_an Array
95 100 json_response.first['body'].should == merge_request_note.note
96 101 end
  102 +
  103 + it "should return a 404 error if merge request id not found" do
  104 + get api("/projects/#{project.id}/merge_requests/4444/notes", user)
  105 + response.status.should == 404
  106 + end
  107 + end
  108 +
  109 + context "when notable is invalid" do
  110 + it "should return a 404 error" do
  111 + get api("/projects/#{project.id}/unknown/#{snippet.id}/notes", user)
  112 + response.status.should == 404
  113 + end
97 114 end
98 115 end
99 116  
... ... @@ -133,6 +150,16 @@ describe Gitlab::API do
133 150 json_response['body'].should == 'hi!'
134 151 json_response['author']['email'].should == user.email
135 152 end
  153 +
  154 + it "should return a 400 bad request error if body not given" do
  155 + post api("/projects/#{project.id}/issues/#{issue.id}/notes", user)
  156 + response.status.should == 400
  157 + end
  158 +
  159 + it "should return a 401 unauthorized error if user not authenticated" do
  160 + post api("/projects/#{project.id}/issues/#{issue.id}/notes"), body: 'hi!'
  161 + response.status.should == 401
  162 + end
136 163 end
137 164  
138 165 context "when noteable is a Snippet" do
... ... @@ -142,6 +169,23 @@ describe Gitlab::API do
142 169 json_response['body'].should == 'hi!'
143 170 json_response['author']['email'].should == user.email
144 171 end
  172 +
  173 + it "should return a 400 bad request error if body not given" do
  174 + post api("/projects/#{project.id}/snippets/#{snippet.id}/notes", user)
  175 + response.status.should == 400
  176 + end
  177 +
  178 + it "should return a 401 unauthorized error if user not authenticated" do
  179 + post api("/projects/#{project.id}/snippets/#{snippet.id}/notes"), body: 'hi!'
  180 + response.status.should == 401
  181 + end
  182 + end
  183 +
  184 + context "when noteable is invalid" do
  185 + it "should return a 404 error" do
  186 + post api("/projects/#{project.id}/invalid/#{snippet.id}/notes", user)
  187 + response.status.should == 404
  188 + end
145 189 end
146 190 end
147 191 end
... ...