Rest Issues » History » Version 70

Mischa The Evil, 2021-07-27 20:38
Explain include=allowed_statuses parameter in more detail.

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