Rest api » History » Version 101
Go MAEDA, 2019-06-16 11:49
1 | 26 | Jean-Philippe Lang | {{>toc}} |
---|---|---|---|
2 | 26 | Jean-Philippe Lang | |
3 | 1 | Jean-Philippe Lang | h1. Redmine API |
4 | 1 | Jean-Philippe Lang | |
5 | 60 | Jean-Philippe Lang | Redmine exposes some of its data through a REST API. This API provides access and basic CRUD operations (create, update, delete) for the resources described below. The API supports both "XML":http://en.wikipedia.org/wiki/Xml and "JSON":http://en.wikipedia.org/wiki/JSON formats. |
6 | 1 | Jean-Philippe Lang | |
7 | 1 | Jean-Philippe Lang | h2. API Description |
8 | 1 | Jean-Philippe Lang | |
9 | 24 | Jean-Philippe Lang | |_.Resource |_.Status |_.Notes |_.Availability| |
10 | 91 | Jean-Philippe Lang | |[[Rest_Issues|Issues]] | Stable | | 1.0 | |
11 | 91 | Jean-Philippe Lang | |[[Rest_Projects|Projects]] | Stable | | 1.0 | |
12 | 55 | Jean-Philippe Lang | |[[Rest_Memberships|Project Memberships]] | Alpha | | 1.4 | |
13 | 56 | Jean-Philippe Lang | |[[Rest_Users|Users]] | Stable | | 1.1 | |
14 | 56 | Jean-Philippe Lang | |[[Rest_TimeEntries|Time Entries]] | Stable | | 1.1 | |
15 | 28 | Jean-Philippe Lang | |[[Rest_News|News]] | Prototype | Prototype implementation for @index@ only | 1.1 | |
16 | 43 | Jean-Philippe Lang | |[[Rest_IssueRelations|Issue Relations]] | Alpha | | 1.3 | |
17 | 43 | Jean-Philippe Lang | |[[Rest_Versions|Versions]] | Alpha | | 1.3 | |
18 | 85 | Jean-Philippe Lang | |[[Rest_WikiPages|Wiki Pages]] | Alpha | | 2.2 | |
19 | 44 | Jean-Philippe Lang | |[[Rest_Queries|Queries]] | Alpha | | 1.3 | |
20 | 63 | Jean-Philippe Lang | |[[Rest_Attachments|Attachments]] | Beta | Adding attachments via the API added in 1.4 | 1.3 | |
21 | 53 | Jean-Philippe Lang | |[[Rest_IssueStatuses|Issue Statuses]] | Alpha | Provides the list of all statuses | 1.3 | |
22 | 51 | Jean-Philippe Lang | |[[Rest_Trackers|Trackers]] | Alpha | Provides the list of all trackers | 1.3 | |
23 | 84 | Jean-Philippe Lang | |[[Rest_Enumerations|Enumerations]] | Alpha | Provides the list of issue priorities and time tracking activities | 2.2 | |
24 | 52 | Jean-Philippe Lang | |[[Rest_IssueCategories|Issue Categories]] | Alpha | | 1.3 | |
25 | 55 | Jean-Philippe Lang | |[[Rest_Roles|Roles]] | Alpha | | 1.4 | |
26 | 79 | Jean-Philippe Lang | |[[Rest_Groups|Groups]] | Alpha | | 2.1 | |
27 | 92 | Jean-Philippe Lang | |[[Rest_CustomFields|Custom Fields]] | Alpha | | 2.4 | |
28 | 95 | Go MAEDA | |[[Rest_Search|Search]] | Alpha | | 3.3 | |
29 | 96 | Go MAEDA | |[[Rest_Files|Files]] | Alpha | | 3.4 | |
30 | 101 | Go MAEDA | |[[Rest_MyAccount|My account]] | Alpha | | 4.1 | |
31 | 24 | Jean-Philippe Lang | |
32 | 15 | Eric Davis | Status legend: |
33 | 1 | Jean-Philippe Lang | |
34 | 1 | Jean-Philippe Lang | * Stable - feature complete, no major changes planned |
35 | 1 | Jean-Philippe Lang | * Beta - usable for integrations with some bugs or missing minor functionality |
36 | 1 | Jean-Philippe Lang | * Alpha - major functionality in place, needs feedback from API users and integrators |
37 | 1 | Jean-Philippe Lang | * Prototype - very rough implementation, possible major breaking changes mid-version. *Not recommended for integration* |
38 | 1 | Jean-Philippe Lang | * Planned - planned in a future version, depending on developer availability |
39 | 1 | Jean-Philippe Lang | |
40 | 97 | Jean-Philippe Lang | You can review the list of all the "API changes for each version":/projects/redmine/issues?set_filter=1&status_id=c&fixed_version_id=*&category_id=32&c[]=tracker&c[]=subject&c[]=author&group_by=fixed_version&sort=fixed_version:desc,id. |
41 | 97 | Jean-Philippe Lang | |
42 | 24 | Jean-Philippe Lang | h2. General topics |
43 | 1 | Jean-Philippe Lang | |
44 | 78 | Jean-Philippe Lang | h3. Specify @Content-Type@ on @POST@/@PUT@ requests |
45 | 66 | Etienne Massip | |
46 | 83 | Jean-Philippe Lang | When creating or updating a remote element, the @Content-Type@ of the request *MUST* be specified even if the remote URL is suffixed accordingly (e.g. @POST ../issues.json@): |
47 | 82 | Jean-Philippe Lang | * for JSON content, it must be set to @Content-Type: application/json@. |
48 | 78 | Jean-Philippe Lang | * for XML content, to @Content-Type: application/xml@. |
49 | 66 | Etienne Massip | |
50 | 24 | Jean-Philippe Lang | h3. Authentication |
51 | 24 | Jean-Philippe Lang | |
52 | 99 | Go MAEDA | Most of the time, the API requires authentication. To enable the API-style authentication, you have to check *Enable REST API* in Administration -> Settings -> API. Then, authentication can be done in 2 different ways: |
53 | 24 | Jean-Philippe Lang | * using your regular login/password via HTTP Basic authentication. |
54 | 38 | Jean-Philippe Lang | * using your API key which is a handy way to avoid putting a password in a script. The API key may be attached to each request in one of the following way: |
55 | 38 | Jean-Philippe Lang | ** passed in as a "key" parameter |
56 | 38 | Jean-Philippe Lang | ** passed in as a username with a random password via HTTP Basic authentication |
57 | 46 | John Galambos | ** passed in as a "X-Redmine-API-Key" HTTP header (added in Redmine 1.1.0) |
58 | 38 | Jean-Philippe Lang | |
59 | 38 | Jean-Philippe Lang | You can find your API key on your account page ( /my/account ) when logged in, on the right-hand pane of the default layout. |
60 | 24 | Jean-Philippe Lang | |
61 | 89 | Jean-Philippe Lang | h3. User Impersonation |
62 | 89 | Jean-Philippe Lang | |
63 | 89 | Jean-Philippe Lang | As of Redmine 2.2.0, you can impersonate user through the REST API by setting the @X-Redmine-Switch-User@ header of your API request. It must be set to a user login (eg. @X-Redmine-Switch-User: jsmith@). This only works when using the API with an administrator account, this header will be ignored when using the API with a regular user account. |
64 | 89 | Jean-Philippe Lang | |
65 | 90 | Jean-Philippe Lang | If the login specified with the @X-Redmine-Switch-User@ header does not exist or is not active, you will receive a 412 error response. |
66 | 90 | Jean-Philippe Lang | |
67 | 24 | Jean-Philippe Lang | h3. Collection resources and pagination |
68 | 24 | Jean-Philippe Lang | |
69 | 98 | Go MAEDA | The response to a GET request on a collection resources (eg. @/issues.xml@, @/users.xml@) generally won't return all the objects available in your database. Redmine version:1.1.0 introduces a common way to query such resources using the following parameters: |
70 | 24 | Jean-Philippe Lang | |
71 | 24 | Jean-Philippe Lang | * @offset@: the offset of the first object to retrieve |
72 | 24 | Jean-Philippe Lang | * @limit@: the number of items to be present in the response (default is 25, maximum is 100) |
73 | 24 | Jean-Philippe Lang | |
74 | 24 | Jean-Philippe Lang | Examples: |
75 | 24 | Jean-Philippe Lang | |
76 | 24 | Jean-Philippe Lang | <pre> |
77 | 24 | Jean-Philippe Lang | GET /issues.xml |
78 | 24 | Jean-Philippe Lang | => returns the 25 first issues |
79 | 24 | Jean-Philippe Lang | |
80 | 24 | Jean-Philippe Lang | GET /issues.xml?limit=100 |
81 | 24 | Jean-Philippe Lang | => returns the 100 first issues |
82 | 24 | Jean-Philippe Lang | |
83 | 24 | Jean-Philippe Lang | GET /issues.xml?offset=30&limit=10 |
84 | 24 | Jean-Philippe Lang | => returns 10 issues from the 30th |
85 | 24 | Jean-Philippe Lang | </pre> |
86 | 24 | Jean-Philippe Lang | |
87 | 98 | Go MAEDA | Responses to GET requests on collection resources provide information about the total object count available in Redmine and the offset/limit used for the response. Examples: |
88 | 24 | Jean-Philippe Lang | |
89 | 24 | Jean-Philippe Lang | <pre> |
90 | 24 | Jean-Philippe Lang | GET /issues.xml |
91 | 24 | Jean-Philippe Lang | |
92 | 24 | Jean-Philippe Lang | <issues type="array" total_count="2595" limit="25" offset="0"> |
93 | 24 | Jean-Philippe Lang | ... |
94 | 24 | Jean-Philippe Lang | </issues> |
95 | 24 | Jean-Philippe Lang | </pre> |
96 | 24 | Jean-Philippe Lang | |
97 | 24 | Jean-Philippe Lang | <pre> |
98 | 24 | Jean-Philippe Lang | GET /issues.json |
99 | 24 | Jean-Philippe Lang | |
100 | 24 | Jean-Philippe Lang | { "issues":[...], "total_count":2595, "limit":25, "offset":0 } |
101 | 24 | Jean-Philippe Lang | </pre> |
102 | 24 | Jean-Philippe Lang | |
103 | 24 | Jean-Philippe Lang | Note: if you're using a REST client that does not support such top level attributes (total_count, limit, offset), you can set the @nometa@ parameter or @X-Redmine-Nometa@ HTTP header to 1 to get responses without them. Example: |
104 | 24 | Jean-Philippe Lang | |
105 | 24 | Jean-Philippe Lang | <pre> |
106 | 24 | Jean-Philippe Lang | GET /issues.xml?nometa=1 |
107 | 24 | Jean-Philippe Lang | |
108 | 24 | Jean-Philippe Lang | <issues type="array"> |
109 | 24 | Jean-Philippe Lang | ... |
110 | 24 | Jean-Philippe Lang | </issues> |
111 | 24 | Jean-Philippe Lang | </pre> |
112 | 23 | Jean-Philippe Lang | |
113 | 29 | Etienne Massip | h3. Fetching associated data |
114 | 29 | Etienne Massip | |
115 | 29 | Etienne Massip | Since of version:1.1.0, you have to explicitly specify the associations you want to be included in the query result by appending the @include@ parameter to the query url : |
116 | 29 | Etienne Massip | |
117 | 29 | Etienne Massip | Example: |
118 | 29 | Etienne Massip | |
119 | 41 | Jean-Philippe Lang | To retrieve issue journals with its description: |
120 | 29 | Etienne Massip | |
121 | 29 | Etienne Massip | <pre> |
122 | 29 | Etienne Massip | GET /issues/296.xml?include=journals |
123 | 29 | Etienne Massip | |
124 | 29 | Etienne Massip | <issue> |
125 | 29 | Etienne Massip | <id>296</id> |
126 | 30 | Etienne Massip | ... |
127 | 29 | Etienne Massip | <journals type="array"> |
128 | 29 | Etienne Massip | ... |
129 | 1 | Jean-Philippe Lang | </journals> |
130 | 41 | Jean-Philippe Lang | </issue> |
131 | 41 | Jean-Philippe Lang | </pre> |
132 | 41 | Jean-Philippe Lang | |
133 | 98 | Go MAEDA | You can also load multiple associations using a comma separated list of items. |
134 | 41 | Jean-Philippe Lang | |
135 | 41 | Jean-Philippe Lang | Example: |
136 | 41 | Jean-Philippe Lang | |
137 | 41 | Jean-Philippe Lang | <pre> |
138 | 41 | Jean-Philippe Lang | GET /issues/296.xml?include=journals,changesets |
139 | 41 | Jean-Philippe Lang | |
140 | 41 | Jean-Philippe Lang | <issue> |
141 | 41 | Jean-Philippe Lang | <id>296</id> |
142 | 41 | Jean-Philippe Lang | ... |
143 | 41 | Jean-Philippe Lang | <journals type="array"> |
144 | 41 | Jean-Philippe Lang | ... |
145 | 41 | Jean-Philippe Lang | </journals> |
146 | 41 | Jean-Philippe Lang | <changesets type="array"> |
147 | 41 | Jean-Philippe Lang | ... |
148 | 41 | Jean-Philippe Lang | </changesets> |
149 | 29 | Etienne Massip | </issue> |
150 | 29 | Etienne Massip | </pre> |
151 | 29 | Etienne Massip | |
152 | 42 | Jean-Philippe Lang | h3. Working with custom fields |
153 | 42 | Jean-Philippe Lang | |
154 | 42 | Jean-Philippe Lang | Most of the Redmine objects support custom fields. Their values can be found in the @custom_fields@ attributes. |
155 | 42 | Jean-Philippe Lang | |
156 | 42 | Jean-Philippe Lang | XML Example: |
157 | 42 | Jean-Philippe Lang | |
158 | 42 | Jean-Philippe Lang | <pre> |
159 | 42 | Jean-Philippe Lang | GET /issues/296.xml # an issue with 2 custom fields |
160 | 42 | Jean-Philippe Lang | |
161 | 42 | Jean-Philippe Lang | <issue> |
162 | 42 | Jean-Philippe Lang | <id>296</id> |
163 | 42 | Jean-Philippe Lang | ... |
164 | 42 | Jean-Philippe Lang | <custom_fields type="array"> |
165 | 42 | Jean-Philippe Lang | <custom_field name="Affected version" id="1"> |
166 | 42 | Jean-Philippe Lang | <value>1.0.1</value> |
167 | 42 | Jean-Philippe Lang | </custom_field> |
168 | 42 | Jean-Philippe Lang | <custom_field name="Resolution" id="2"> |
169 | 42 | Jean-Philippe Lang | <value>Fixed</value> |
170 | 42 | Jean-Philippe Lang | </custom_field> |
171 | 42 | Jean-Philippe Lang | </custom_fields> |
172 | 42 | Jean-Philippe Lang | </issue> |
173 | 42 | Jean-Philippe Lang | </pre> |
174 | 42 | Jean-Philippe Lang | |
175 | 42 | Jean-Philippe Lang | JSON Example: |
176 | 42 | Jean-Philippe Lang | |
177 | 42 | Jean-Philippe Lang | <pre> |
178 | 42 | Jean-Philippe Lang | GET /issues/296.json # an issue with 2 custom fields |
179 | 42 | Jean-Philippe Lang | |
180 | 42 | Jean-Philippe Lang | {"issue": |
181 | 42 | Jean-Philippe Lang | { |
182 | 42 | Jean-Philippe Lang | "id":8471, |
183 | 42 | Jean-Philippe Lang | ... |
184 | 42 | Jean-Philippe Lang | "custom_fields": |
185 | 42 | Jean-Philippe Lang | [ |
186 | 42 | Jean-Philippe Lang | {"value":"1.0.1","name":"Affected version","id":1}, |
187 | 42 | Jean-Philippe Lang | {"value":"Fixed","name":"Resolution","id":2} |
188 | 42 | Jean-Philippe Lang | ] |
189 | 42 | Jean-Philippe Lang | } |
190 | 42 | Jean-Philippe Lang | } |
191 | 42 | Jean-Philippe Lang | </pre> |
192 | 42 | Jean-Philippe Lang | |
193 | 42 | Jean-Philippe Lang | You can also set/change the values of the custom fields when creating/updating an object using the same syntax (except that the custom field name is not required). |
194 | 42 | Jean-Philippe Lang | |
195 | 42 | Jean-Philippe Lang | XML Example: |
196 | 42 | Jean-Philippe Lang | |
197 | 42 | Jean-Philippe Lang | <pre> |
198 | 42 | Jean-Philippe Lang | PUT /issues/296.xml |
199 | 42 | Jean-Philippe Lang | |
200 | 42 | Jean-Philippe Lang | <issue> |
201 | 42 | Jean-Philippe Lang | <subject>Updating custom fields of an issue</subject> |
202 | 42 | Jean-Philippe Lang | ... |
203 | 42 | Jean-Philippe Lang | <custom_fields type="array"> |
204 | 42 | Jean-Philippe Lang | <custom_field id="1"> |
205 | 42 | Jean-Philippe Lang | <value>1.0.2</value> |
206 | 42 | Jean-Philippe Lang | </custom_field> |
207 | 42 | Jean-Philippe Lang | <custom_field id="2"> |
208 | 42 | Jean-Philippe Lang | <value>Invalid</value> |
209 | 42 | Jean-Philippe Lang | </custom_field> |
210 | 42 | Jean-Philippe Lang | </custom_fields> |
211 | 42 | Jean-Philippe Lang | </issue> |
212 | 42 | Jean-Philippe Lang | </pre> |
213 | 42 | Jean-Philippe Lang | |
214 | 42 | Jean-Philippe Lang | Note: the @type="array"@ attribute on @custom_fields@ XML tag is strictly required. |
215 | 42 | Jean-Philippe Lang | |
216 | 42 | Jean-Philippe Lang | JSON Example: |
217 | 42 | Jean-Philippe Lang | |
218 | 42 | Jean-Philippe Lang | <pre> |
219 | 42 | Jean-Philippe Lang | PUT /issues/296.json |
220 | 42 | Jean-Philippe Lang | |
221 | 42 | Jean-Philippe Lang | {"issue": |
222 | 42 | Jean-Philippe Lang | { |
223 | 42 | Jean-Philippe Lang | "subject":"Updating custom fields of an issue", |
224 | 42 | Jean-Philippe Lang | ... |
225 | 42 | Jean-Philippe Lang | "custom_fields": |
226 | 42 | Jean-Philippe Lang | [ |
227 | 42 | Jean-Philippe Lang | {"value":"1.0.2","id":1}, |
228 | 42 | Jean-Philippe Lang | {"value":"Invalid","id":2} |
229 | 42 | Jean-Philippe Lang | ] |
230 | 42 | Jean-Philippe Lang | } |
231 | 42 | Jean-Philippe Lang | } |
232 | 42 | Jean-Philippe Lang | </pre> |
233 | 42 | Jean-Philippe Lang | |
234 | 61 | Jean-Philippe Lang | h3. Attaching files |
235 | 61 | Jean-Philippe Lang | |
236 | 61 | Jean-Philippe Lang | Support for adding attachments through the REST API is added in Redmine version:1.4.0. |
237 | 61 | Jean-Philippe Lang | |
238 | 93 | Jean-Philippe Lang | First, you need to upload each file with a POST request to @/uploads.xml@ (or @/uploads.json@). The request body should be the content of the file you want to attach and the @Content-Type@ header must be set to @application/octet-stream@ (otherwise you'll get a @406 Not Acceptable@ response). If the upload succeeds, you get a 201 response that contains a token for your uploaded file. |
239 | 1 | Jean-Philippe Lang | |
240 | 93 | Jean-Philippe Lang | Then you can use this token to attach your uploaded file to a new or an existing issue. |
241 | 93 | Jean-Philippe Lang | |
242 | 93 | Jean-Philippe Lang | +XML Example+ |
243 | 93 | Jean-Philippe Lang | |
244 | 93 | Jean-Philippe Lang | First, upload your file: |
245 | 93 | Jean-Philippe Lang | |
246 | 61 | Jean-Philippe Lang | <pre> |
247 | 100 | Go MAEDA | POST /uploads.xml?filename=image.png |
248 | 61 | Jean-Philippe Lang | Content-Type: application/octet-stream |
249 | 61 | Jean-Philippe Lang | ... |
250 | 61 | Jean-Philippe Lang | (request body is the file content) |
251 | 61 | Jean-Philippe Lang | |
252 | 61 | Jean-Philippe Lang | # 201 response |
253 | 61 | Jean-Philippe Lang | <upload> |
254 | 61 | Jean-Philippe Lang | <token>7167.ed1ccdb093229ca1bd0b043618d88743</token> |
255 | 61 | Jean-Philippe Lang | </upload> |
256 | 1 | Jean-Philippe Lang | </pre> |
257 | 61 | Jean-Philippe Lang | |
258 | 93 | Jean-Philippe Lang | Then create the issue using the upload token: |
259 | 61 | Jean-Philippe Lang | |
260 | 61 | Jean-Philippe Lang | <pre> |
261 | 61 | Jean-Philippe Lang | POST /issues.xml |
262 | 61 | Jean-Philippe Lang | <issue> |
263 | 61 | Jean-Philippe Lang | <project_id>1</project_id> |
264 | 61 | Jean-Philippe Lang | <subject>Creating an issue with a uploaded file</subject> |
265 | 62 | Jean-Philippe Lang | <uploads type="array"> |
266 | 61 | Jean-Philippe Lang | <upload> |
267 | 61 | Jean-Philippe Lang | <token>7167.ed1ccdb093229ca1bd0b043618d88743</token> |
268 | 61 | Jean-Philippe Lang | <filename>image.png</filename> |
269 | 86 | Etienne Massip | <description>An optional description here</description> |
270 | 61 | Jean-Philippe Lang | <content_type>image/png</content_type> |
271 | 61 | Jean-Philippe Lang | </upload> |
272 | 61 | Jean-Philippe Lang | </uploads> |
273 | 61 | Jean-Philippe Lang | </issue> |
274 | 61 | Jean-Philippe Lang | </pre> |
275 | 61 | Jean-Philippe Lang | |
276 | 64 | Jean-Philippe Lang | If you try to upload a file that exceeds the maximum size allowed, you get a 422 response: |
277 | 64 | Jean-Philippe Lang | |
278 | 64 | Jean-Philippe Lang | <pre> |
279 | 100 | Go MAEDA | POST /uploads.xml?filename=image.png |
280 | 64 | Jean-Philippe Lang | Content-Type: application/octet-stream |
281 | 64 | Jean-Philippe Lang | ... |
282 | 64 | Jean-Philippe Lang | (request body larger than the maximum size allowed) |
283 | 64 | Jean-Philippe Lang | |
284 | 64 | Jean-Philippe Lang | # 422 response |
285 | 64 | Jean-Philippe Lang | <errors> |
286 | 1 | Jean-Philippe Lang | <error>This file cannot be uploaded because it exceeds the maximum allowed file size (1024000)</error> |
287 | 1 | Jean-Philippe Lang | </errors> |
288 | 93 | Jean-Philippe Lang | </pre> |
289 | 93 | Jean-Philippe Lang | |
290 | 93 | Jean-Philippe Lang | +JSON Example+ |
291 | 93 | Jean-Philippe Lang | |
292 | 93 | Jean-Philippe Lang | First, upload your file: |
293 | 93 | Jean-Philippe Lang | |
294 | 93 | Jean-Philippe Lang | <pre> |
295 | 100 | Go MAEDA | POST /uploads.json?filename=image.png |
296 | 93 | Jean-Philippe Lang | Content-Type: application/octet-stream |
297 | 93 | Jean-Philippe Lang | ... |
298 | 93 | Jean-Philippe Lang | (request body is the file content) |
299 | 93 | Jean-Philippe Lang | |
300 | 93 | Jean-Philippe Lang | # 201 response |
301 | 93 | Jean-Philippe Lang | {"upload":{"token":"7167.ed1ccdb093229ca1bd0b043618d88743"}} |
302 | 93 | Jean-Philippe Lang | </pre> |
303 | 93 | Jean-Philippe Lang | |
304 | 93 | Jean-Philippe Lang | Then create the issue using the upload token: |
305 | 93 | Jean-Philippe Lang | |
306 | 93 | Jean-Philippe Lang | <pre> |
307 | 93 | Jean-Philippe Lang | POST /issues.json |
308 | 93 | Jean-Philippe Lang | { |
309 | 93 | Jean-Philippe Lang | "issue": { |
310 | 93 | Jean-Philippe Lang | "project_id": "1", |
311 | 93 | Jean-Philippe Lang | "subject": "Creating an issue with a uploaded file", |
312 | 93 | Jean-Philippe Lang | "uploads": [ |
313 | 93 | Jean-Philippe Lang | {"token": "7167.ed1ccdb093229ca1bd0b043618d88743", "filename": "image.png", "content_type": "image/png"} |
314 | 93 | Jean-Philippe Lang | ] |
315 | 93 | Jean-Philippe Lang | } |
316 | 93 | Jean-Philippe Lang | } |
317 | 93 | Jean-Philippe Lang | </pre> |
318 | 93 | Jean-Philippe Lang | |
319 | 93 | Jean-Philippe Lang | You can also upload multiple files (by doing multiple POST requests to @/uploads.json@), then create an issue with multiple attachments: |
320 | 93 | Jean-Philippe Lang | |
321 | 93 | Jean-Philippe Lang | <pre> |
322 | 93 | Jean-Philippe Lang | POST /issues.json |
323 | 93 | Jean-Philippe Lang | { |
324 | 93 | Jean-Philippe Lang | "issue": { |
325 | 93 | Jean-Philippe Lang | "project_id": "1", |
326 | 93 | Jean-Philippe Lang | "subject": "Creating an issue with a uploaded file", |
327 | 93 | Jean-Philippe Lang | "uploads": [ |
328 | 93 | Jean-Philippe Lang | {"token": "7167.ed1ccdb093229ca1bd0b043618d88743", "filename": "image1.png", "content_type": "image/png"}, |
329 | 93 | Jean-Philippe Lang | {"token": "7168.d595398bbb104ed3bba0eed666785cc6", "filename": "image2.png", "content_type": "image/png"} |
330 | 93 | Jean-Philippe Lang | ] |
331 | 93 | Jean-Philippe Lang | } |
332 | 93 | Jean-Philippe Lang | } |
333 | 64 | Jean-Philippe Lang | </pre> |
334 | 64 | Jean-Philippe Lang | |
335 | 59 | Jean-Philippe Lang | h3. Validation errors |
336 | 59 | Jean-Philippe Lang | |
337 | 59 | Jean-Philippe Lang | When trying to create or update an object with invalid or missing attribute parameters, you will get a @422 Unprocessable Entity@ response. That means that the object could not be created or updated. In such cases, the response body contains the corresponding error messages: |
338 | 59 | Jean-Philippe Lang | |
339 | 59 | Jean-Philippe Lang | +XML Example+: |
340 | 59 | Jean-Philippe Lang | |
341 | 59 | Jean-Philippe Lang | <pre> |
342 | 59 | Jean-Philippe Lang | # Request with invalid or missing attributes |
343 | 59 | Jean-Philippe Lang | POST /users.xml |
344 | 59 | Jean-Philippe Lang | <user> |
345 | 59 | Jean-Philippe Lang | <login>john</login> |
346 | 59 | Jean-Philippe Lang | <lastname>Smith</lastname> |
347 | 59 | Jean-Philippe Lang | <mail>john</mail> |
348 | 59 | Jean-Philippe Lang | </uer> |
349 | 59 | Jean-Philippe Lang | |
350 | 59 | Jean-Philippe Lang | # 422 response with the error messages in its body |
351 | 65 | Jean-Philippe Lang | <errors type="array"> |
352 | 59 | Jean-Philippe Lang | <error>First name can't be blank</error> |
353 | 59 | Jean-Philippe Lang | <error>Email is invalid</error> |
354 | 59 | Jean-Philippe Lang | </errors> |
355 | 59 | Jean-Philippe Lang | </pre> |
356 | 59 | Jean-Philippe Lang | |
357 | 59 | Jean-Philippe Lang | |
358 | 59 | Jean-Philippe Lang | +JSON Example+: |
359 | 59 | Jean-Philippe Lang | |
360 | 59 | Jean-Philippe Lang | <pre> |
361 | 59 | Jean-Philippe Lang | # Request with invalid or missing attributes |
362 | 59 | Jean-Philippe Lang | POST /users.json |
363 | 59 | Jean-Philippe Lang | { |
364 | 59 | Jean-Philippe Lang | "user":{ |
365 | 59 | Jean-Philippe Lang | "login":"john", |
366 | 59 | Jean-Philippe Lang | "lastname":"Smith", |
367 | 59 | Jean-Philippe Lang | "mail":"john" |
368 | 59 | Jean-Philippe Lang | } |
369 | 59 | Jean-Philippe Lang | } |
370 | 59 | Jean-Philippe Lang | |
371 | 59 | Jean-Philippe Lang | # 422 response with the error messages in its body |
372 | 59 | Jean-Philippe Lang | { |
373 | 59 | Jean-Philippe Lang | "errors":[ |
374 | 59 | Jean-Philippe Lang | "First name can't be blank", |
375 | 59 | Jean-Philippe Lang | "Email is invalid" |
376 | 59 | Jean-Philippe Lang | ] |
377 | 59 | Jean-Philippe Lang | } |
378 | 59 | Jean-Philippe Lang | </pre> |
379 | 59 | Jean-Philippe Lang | |
380 | 81 | Jean-Philippe Lang | h3. JSONP Support |
381 | 81 | Jean-Philippe Lang | |
382 | 99 | Go MAEDA | Redmine 2.1.0+ API supports "JSONP":http://en.wikipedia.org/wiki/JSONP to request data from a Redmine server in a different domain (say, with JQuery). The callback can be passed using the @callback@ or @jsonp@ parameter. As of Redmine 2.3.0, JSONP support is optional and disabled by default, you can enable it by checking *Enable JSONP support* in Administration -> Settings -> API. |
383 | 81 | Jean-Philippe Lang | |
384 | 81 | Jean-Philippe Lang | Example: |
385 | 81 | Jean-Philippe Lang | |
386 | 81 | Jean-Philippe Lang | <pre> |
387 | 81 | Jean-Philippe Lang | GET /issues.json?callback=myHandler |
388 | 81 | Jean-Philippe Lang | |
389 | 81 | Jean-Philippe Lang | myHandler({"issues":[ ... ]}) |
390 | 81 | Jean-Philippe Lang | </pre> |
391 | 81 | Jean-Philippe Lang | |
392 | 1 | Jean-Philippe Lang | h2. API Usage in various languages/tools |
393 | 5 | Jean-Philippe Lang | |
394 | 1 | Jean-Philippe Lang | * [[Rest_api_with_ruby|Ruby]] |
395 | 1 | Jean-Philippe Lang | * [[Rest_api_with_php|PHP]] |
396 | 23 | Jean-Philippe Lang | * [[Rest_api_with_python|Python]] |
397 | 94 | Go MAEDA | * [[Rest_api_with_perl|Perl]] |
398 | 27 | Jean-Philippe Lang | * [[Rest_api_with_java|Java]] |
399 | 1 | Jean-Philippe Lang | * [[Rest_api_with_curl|cURL]] |
400 | 37 | Bevan Rudge | * "Drupal Redmine API module, 2.x branch (currently not stable)":http://drupal.org/project/redmine |
401 | 48 | Dorin Huzum | * [[Rest_api_with_csharp|.NET]] |
402 | 49 | Rodrigo Carvalho | * [[Rest_api_with_delphi|Delphi]] |
403 | 54 | Jean-Philippe Lang | |
404 | 54 | Jean-Philippe Lang | h2. API Change history |
405 | 1 | Jean-Philippe Lang | |
406 | 97 | Jean-Philippe Lang | This section lists changes to the existing API features that may have broken backward compatibility. New features of the API are listed in the [[Rest_api#API-Description|API Description]]. |
407 | 57 | Jean-Philippe Lang | |
408 | 54 | Jean-Philippe Lang | h3. 2012-01-29: Multiselect custom fields (r8721, version:1.4.0) |
409 | 54 | Jean-Philippe Lang | |
410 | 54 | Jean-Philippe Lang | Custom fields with multiple values are now supported in Redmine and may be found in API responses. These custom fields have a @multiple=true attribute@ and their @value@ attribute is an array. |
411 | 54 | Jean-Philippe Lang | |
412 | 54 | Jean-Philippe Lang | Example: |
413 | 54 | Jean-Philippe Lang | |
414 | 54 | Jean-Philippe Lang | <pre> |
415 | 54 | Jean-Philippe Lang | GET /issues/296.json |
416 | 54 | Jean-Philippe Lang | |
417 | 54 | Jean-Philippe Lang | {"issue": |
418 | 54 | Jean-Philippe Lang | { |
419 | 54 | Jean-Philippe Lang | "id":8471, |
420 | 54 | Jean-Philippe Lang | ... |
421 | 54 | Jean-Philippe Lang | "custom_fields": |
422 | 54 | Jean-Philippe Lang | [ |
423 | 54 | Jean-Philippe Lang | {"value":["1.0.1","1.0.2"],"multiple":true,"name":"Affected version","id":1}, |
424 | 54 | Jean-Philippe Lang | {"value":"Fixed","name":"Resolution","id":2} |
425 | 54 | Jean-Philippe Lang | ] |
426 | 54 | Jean-Philippe Lang | } |
427 | 54 | Jean-Philippe Lang | } |
428 | 54 | Jean-Philippe Lang | </pre> |