Project

General

Profile

Rest Issues » History » Version 66

Toshi MARUYAMA, 2019-10-18 16:03
split POST /issues.xml pre tag

1 1 Jean-Philippe Lang
h1. Issues
2
3 28 Jean-Philippe Lang
{{>toc}}
4
5 1 Jean-Philippe Lang
h2. Listing issues
6
7 45 Jean-Philippe Lang
  GET /issues.[format]
8 1 Jean-Philippe Lang
9 2 Jean-Philippe Lang
Returns a paginated list of issues. By default, it returns open issues only.
10 1 Jean-Philippe Lang
11
+Parameters+:
12 26 Etienne Massip
13 21 Alex Last
* @offset@: skip this number of issues in response (optional)
14
* @limit@: number of issues per page (optional)
15 36 Emmanuel Bourgerie
* @sort@: column to sort with. Append @:desc@ to invert the order.
16 62 Bubi =
* @include@: fetch associated data (optional, use comma to fetch multiple associations). Some possible values (for full list see below):
17 58 Go MAEDA
18
  * @attachments@ - Since 3.4.0
19
  * @relations@
20 61 Bubi =
  * @journals@
21 64 Valerio Di Biasi
  * @children@
22 23 Alex Last
23 2 Jean-Philippe Lang
Optional filters:
24
25 56 Rafael Dantas
* @issue_id@: get issue with the given id or multiple issues by id using ',' to separate id.
26 55 Go MAEDA
* @project_id@: get issues from the project with the given id (a numeric value, not a project identifier).
27 40 Matthias Lamoureux
* @subproject_id@: get issues from the subproject with the given id. You can use @project_id=XXX&subproject_id=!*@ to get only the issues of a given project and none of its subprojects.
28 2 Jean-Philippe Lang
* @tracker_id@: get issues from the tracker with the given id
29 33 Ilya Kulakov
* @status_id@: get issues with the given status id only. Possible values: @open@, @closed@, @*@ to get open and closed issues, status id
30 52 davi vidal
* @assigned_to_id@: get issues which are assigned to the given user id. @me@ can be used instead an ID to fetch all issues from the logged in user (via API key or HTTP auth)
31 57 Go MAEDA
* @parent_id@: get issues whose parent issue is given id.
32 25 John Manktelow
* @cf_x@: get issues with the given value for custom field with an ID of @x@. (Custom field must have 'used as a filter' checked.)
33 2 Jean-Philippe Lang
* ...
34
35 47 Jean-Baptiste Barth
NB: operators containing ">", "<" or "=" should be hex-encoded so they're parsed correctly. Most evolved API clients will do that for you by default, but for the sake of clarity the following examples have been written with no such magic feature in mind.
36
37 2 Jean-Philippe Lang
+Examples+:
38
39
<pre>
40
GET /issues.xml
41 63 Go MAEDA
GET /issues.xml?issue_id=1
42
GET /issues.xml?issue_id=1,2
43 2 Jean-Philippe Lang
GET /issues.xml?project_id=2
44 1 Jean-Philippe Lang
GET /issues.xml?project_id=2&tracker_id=1
45
GET /issues.xml?assigned_to_id=6
46 52 davi vidal
GET /issues.xml?assigned_to_id=me
47 12 Robert Palmer
GET /issues.xml?status_id=closed
48 1 Jean-Philippe Lang
GET /issues.xml?status_id=*
49 25 John Manktelow
GET /issues.xml?cf_1=abcdef
50 48 Filou Centrinov
GET /issues.xml?sort=category:desc,updated_on
51 56 Rafael Dantas
52 21 Alex Last
53
Paging example:
54 45 Jean-Philippe Lang
GET /issues.xml?offset=0&limit=100
55 1 Jean-Philippe Lang
GET /issues.xml?offset=100&limit=100
56
57 47 Jean-Baptiste Barth
To fetch issues for a date range (uncrypted filter is "><2012-03-01|2012-03-07") :
58
GET /issues.xml?created_on=%3E%3C2012-03-01|2012-03-07
59
60
To fetch issues created after a certain date (uncrypted filter is ">=2012-03-01") :
61
GET /issues.xml?created_on=%3E%3D2012-03-01
62
63
Or before a certain date (uncrypted filter is "<= 2012-03-07") :
64
GET /issues.xml?created_on=%3C%3D2012-03-07
65 51 Jean-Philippe Lang
66
To fetch issues created after a certain timestamp (uncrypted filter is ">=2014-01-02T08:12:32Z") :
67
GET /issues.xml?created_on=%3E%3D2014-01-02T08:12:32Z
68
69
To fetch issues updated after a certain timestamp (uncrypted filter is ">=2014-01-02T08:12:32Z") :
70
GET /issues.xml?updated_on=%3E%3D2014-01-02T08:12:32Z
71 65 Stéphane Lavergne
72
To fetch issues for which custom field 4 contains the substring "foo" :
73
GET /issues.xml?cf_4=~foo
74 12 Robert Palmer
</pre>
75 1 Jean-Philippe Lang
76
+Response+:
77
78 59 Toshi MARUYAMA
<pre><code class="xml">
79 1 Jean-Philippe Lang
<?xml version="1.0" encoding="UTF-8"?>
80
<issues type="array" count="1640">
81 3 Christoph Witzany
  <issue>
82
    <id>4326</id>
83 1 Jean-Philippe Lang
    <project name="Redmine" id="1"/>
84
    <tracker name="Feature" id="2"/>
85
    <status name="New" id="1"/>
86
    <priority name="Normal" id="4"/>
87
    <author name="John Smith" id="10106"/>
88
    <category name="Email notifications" id="9"/>
89
    <subject>
90
      Aggregate Multiple Issue Changes for Email Notifications
91
    </subject>
92
    <description>
93
      This is not to be confused with another useful proposed feature that
94
      would do digest emails for notifications.
95
    </description>
96
    <start_date>2009-12-03</start_date>
97
    <due_date></due_date>
98
    <done_ratio>0</done_ratio>
99
    <estimated_hours></estimated_hours>
100
    <custom_fields>
101
      <custom_field name="Resolution" id="2">Duplicate</custom_field>
102
      <custom_field name="Texte" id="5">Test</custom_field>
103
      <custom_field name="Boolean" id="6">1</custom_field>
104
      <custom_field name="Date" id="7">2010-01-12</custom_field>
105
    </custom_fields>
106
    <created_on>Thu Dec 03 15:02:12 +0100 2009</created_on>
107
    <updated_on>Sun Jan 03 12:08:41 +0100 2010</updated_on>
108
  </issue>
109 3 Christoph Witzany
  <issue>
110
    <id>4325</id>
111 1 Jean-Philippe Lang
    ...
112
  </issue>
113
</issues>
114 59 Toshi MARUYAMA
</code></pre>
115 1 Jean-Philippe Lang
116
h2. Showing an issue
117
118 31 Ilya Kulakov
<pre>
119 43 Jean-Philippe Lang
GET /issues/[id].[format]
120 31 Ilya Kulakov
</pre>
121
122 43 Jean-Philippe Lang
+Parameters+:
123 1 Jean-Philippe Lang
124 43 Jean-Philippe Lang
* @include@: fetch associated data (optional, use comma to fetch multiple associations). Possible values:
125 1 Jean-Philippe Lang
126 43 Jean-Philippe Lang
  * @children@
127
  * @attachments@
128
  * @relations@
129
  * @changesets@
130
  * @journals@ - See [[Rest_IssueJournals|Issue journals]] for more information.
131
  * @watchers@ - Since 2.3.0
132 1 Jean-Philippe Lang
133 43 Jean-Philippe Lang
+Examples+:
134
135
<pre>
136
GET /issues/2.xml
137
GET /issues/2.json
138
139
GET /issues/2.xml
140
GET /issues/2.xml?include=attachments
141 1 Jean-Philippe Lang
GET /issues/2.xml?include=attachments,journals
142 43 Jean-Philippe Lang
</pre>
143
144 1 Jean-Philippe Lang
h2. Creating an issue
145
146 45 Jean-Philippe Lang
  POST /issues.[format]
147 1 Jean-Philippe Lang
148 45 Jean-Philippe Lang
+Parameters+:
149 1 Jean-Philippe Lang
150 45 Jean-Philippe Lang
* @issue@ - A hash of the issue attributes:
151 1 Jean-Philippe Lang
152 45 Jean-Philippe Lang
  * @project_id@
153
  * @tracker_id@
154
  * @status_id@
155 50 redmineservices .
  * @priority_id@
156 45 Jean-Philippe Lang
  * @subject@
157
  * @description@
158
  * @category_id@
159 49 Maarten Verwijs
  * @fixed_version_id@ - ID of the Target Versions (previously called 'Fixed Version' and still referred to as such in the API)
160 45 Jean-Philippe Lang
  * @assigned_to_id@ - ID of the user to assign the issue to (currently no mechanism to assign by name)
161
  * @parent_issue_id@ - ID of the parent issue
162
  * @custom_fields@ - See [[Rest_api#Working-with-custom-fields|Custom fields]]
163
  * @watcher_user_ids@ - Array of user ids to add as watchers (since 2.3.0)
164 53 Matt Wiseley
  * @is_private@ - Use true or false to indicate whether the issue is private or not
165
  * @estimated_hours@ - Number of hours estimated for issue
166 45 Jean-Philippe Lang
167 1 Jean-Philippe Lang
Attachments can be added when you create an issue, see [[Rest_api#Attaching-files|Attaching files]].
168
169 45 Jean-Philippe Lang
+Examples+:
170 1 Jean-Philippe Lang
171 66 Toshi MARUYAMA
<pre>
172 1 Jean-Philippe Lang
POST /issues.xml
173 66 Toshi MARUYAMA
</pre>
174
<pre><code class="xml">
175 45 Jean-Philippe Lang
<?xml version="1.0"?>
176
<issue>
177
  <project_id>1</project_id>
178 1 Jean-Philippe Lang
  <subject>Example</subject>
179
  <priority_id>4</priority_id>
180 45 Jean-Philippe Lang
</issue>
181 59 Toshi MARUYAMA
</code></pre>
182 1 Jean-Philippe Lang
<pre>
183
POST /issues.json
184 59 Toshi MARUYAMA
</pre>
185
<pre><code class="json">
186 45 Jean-Philippe Lang
{
187
  "issue": {
188
    "project_id": 1,
189
    "subject": "Example",
190
    "priority_id": 4
191
  }
192
}
193 59 Toshi MARUYAMA
</code></pre>
194 45 Jean-Philippe Lang
195 38 Jean-Philippe Lang
h2. Updating an issue
196 5 Damien Churchill
197 45 Jean-Philippe Lang
  PUT /issues/[id].[format]
198 5 Damien Churchill
199 45 Jean-Philippe Lang
+Parameters+:
200 5 Damien Churchill
201 45 Jean-Philippe Lang
* @issue@ - A hash of the issue attributes
202 27 Stéphane Schoorens
203 45 Jean-Philippe Lang
  * @project_id@
204
  * @tracker_id@
205
  * @status_id@
206
  * @subject@
207
  * ...
208
  * @notes@ - Comments about the update
209 54 Matt Wiseley
  * @private_notes@ - true if notes are private
210 1 Jean-Philippe Lang
211
Attachments can be added when you update an issue, see [[Rest_api#Attaching-files|Attaching files]].
212
213
+Examples+:
214
215 45 Jean-Philippe Lang
<pre>
216
PUT /issues/[id].xml
217 59 Toshi MARUYAMA
</pre>
218
219
<pre>
220
<code class="xml">
221 45 Jean-Philippe Lang
<?xml version="1.0"?>
222 1 Jean-Philippe Lang
<issue>
223
  <subject>Subject changed</subject>
224
  <notes>The subject was changed</notes>
225 45 Jean-Philippe Lang
</issue>
226 59 Toshi MARUYAMA
</code></pre>
227 45 Jean-Philippe Lang
228
<pre>
229
PUT /issues/[id].json
230 59 Toshi MARUYAMA
</pre>
231
232
<pre><code class="json">
233 45 Jean-Philippe Lang
{
234
  "issue": {
235
    "subject": "Subject changed",
236
    "notes": "The subject was changed"
237
  }
238 1 Jean-Philippe Lang
}
239 45 Jean-Philippe Lang
</pre>
240 44 Jean-Philippe Lang
241
h2. Deleting an issue
242
243 45 Jean-Philippe Lang
  DELETE /issues/[id].[format]
244 44 Jean-Philippe Lang
245 46 Jean-Philippe Lang
h2. Adding a watcher 
246 1 Jean-Philippe Lang
247 46 Jean-Philippe Lang
_Added in 2.3.0_
248
249 44 Jean-Philippe Lang
  POST /issues/[id]/watchers.[format]
250
251
+Parameters+:
252
253
* @user_id@ (required): id of the user to add as a watcher
254
255 1 Jean-Philippe Lang
h2. Removing a watcher
256 46 Jean-Philippe Lang
257
_Added in 2.3.0_
258 1 Jean-Philippe Lang
259
  DELETE /issues/[id]/watchers/[user_id].[format]
260
261
+Parameters+: _none_