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 ### List project wall notes 3 ### List project wall notes
4 4
@@ -30,22 +30,59 @@ Parameters: @@ -30,22 +30,59 @@ Parameters:
30 30
31 + `id` (required) - The ID of a project 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 Parameters: 47 Parameters:
42 48
43 + `id` (required) - The ID of a project 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 GET /projects/:id/issues/:issue_id/notes 88 GET /projects/:id/issues/:issue_id/notes
@@ -56,54 +93,85 @@ Parameters: @@ -56,54 +93,85 @@ Parameters:
56 + `id` (required) - The ID of a project 93 + `id` (required) - The ID of a project
57 + `issue_id` (required) - The ID of an issue 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 Parameters: 111 Parameters:
68 112
69 + `id` (required) - The ID of a project 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 Parameters: 132 Parameters:
83 133
84 + `id` (required) - The ID of a project 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 Parameters: 157 Parameters:
96 158
97 + `id` (required) - The ID of a project 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 Parameters: 177 Parameters:
@@ -112,52 +180,97 @@ Parameters: @@ -112,52 +180,97 @@ Parameters:
112 + `snippet_id` (required) - The ID of a project snippet 180 + `snippet_id` (required) - The ID of a project snippet
113 + `note_id` (required) - The ID of an snippet note 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 Parameters: 198 Parameters:
126 199
127 + `id` (required) - The ID of a project 200 + `id` (required) - The ID of a project
  201 ++ `snippet_id` (required) - The ID of an snippet
128 + `body` (required) - The content of a note 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 Parameters: 223 Parameters:
142 224
143 + `id` (required) - The ID of a project 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 Parameters: 243 Parameters:
158 244
159 + `id` (required) - The ID of a project 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 + `body` (required) - The content of a note 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,6 +37,8 @@ module Gitlab
37 # Example Request: 37 # Example Request:
38 # POST /projects/:id/notes 38 # POST /projects/:id/notes
39 post ":id/notes" do 39 post ":id/notes" do
  40 + bad_request!(:body) unless params[:body].present?
  41 +
40 @note = user_project.notes.new(note: params[:body]) 42 @note = user_project.notes.new(note: params[:body])
41 @note.author = current_user 43 @note.author = current_user
42 44
@@ -91,6 +93,9 @@ module Gitlab @@ -91,6 +93,9 @@ module Gitlab
91 # POST /projects/:id/issues/:noteable_id/notes 93 # POST /projects/:id/issues/:noteable_id/notes
92 # POST /projects/:id/snippets/:noteable_id/notes 94 # POST /projects/:id/snippets/:noteable_id/notes
93 post ":id/#{noteables_str}/:#{noteable_id_str}/notes" do 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 @noteable = user_project.send(:"#{noteables_str}").find(params[:"#{noteable_id_str}"]) 99 @noteable = user_project.send(:"#{noteables_str}").find(params[:"#{noteable_id_str}"])
95 @note = @noteable.notes.new(note: params[:body]) 100 @note = @noteable.notes.new(note: params[:body])
96 @note.author = current_user 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,7 +52,12 @@ describe Gitlab::API do
52 json_response['body'].should == 'hi!' 52 json_response['body'].should == 'hi!'
53 end 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 post api("/projects/#{project.id}/notes", user) 61 post api("/projects/#{project.id}/notes", user)
57 response.status.should == 400 62 response.status.should == 400
58 end 63 end
@@ -94,6 +99,18 @@ describe Gitlab::API do @@ -94,6 +99,18 @@ describe Gitlab::API do
94 json_response.should be_an Array 99 json_response.should be_an Array
95 json_response.first['body'].should == merge_request_note.note 100 json_response.first['body'].should == merge_request_note.note
96 end 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 end 114 end
98 end 115 end
99 116
@@ -133,6 +150,16 @@ describe Gitlab::API do @@ -133,6 +150,16 @@ describe Gitlab::API do
133 json_response['body'].should == 'hi!' 150 json_response['body'].should == 'hi!'
134 json_response['author']['email'].should == user.email 151 json_response['author']['email'].should == user.email
135 end 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 end 163 end
137 164
138 context "when noteable is a Snippet" do 165 context "when noteable is a Snippet" do
@@ -142,6 +169,23 @@ describe Gitlab::API do @@ -142,6 +169,23 @@ describe Gitlab::API do
142 json_response['body'].should == 'hi!' 169 json_response['body'].should == 'hi!'
143 json_response['author']['email'].should == user.email 170 json_response['author']['email'].should == user.email
144 end 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 end 189 end
146 end 190 end
147 end 191 end