Rest Issues » History » Version 65

Stéphane Lavergne, 2018-12-06 18:29
Add example for undocumented ~ filtering operator

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 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 58 Go MAEDA
  * @attachments@ - Since 3.4.0
19 58 Go MAEDA
  * @relations@
20 61 Bubi =
  * @journals@
21 64 Valerio Di Biasi
  * @children@
22 23 Alex Last
23 2 Jean-Philippe Lang
Optional filters:
24 2 Jean-Philippe Lang
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 2 Jean-Philippe Lang
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 47 Jean-Baptiste Barth
37 2 Jean-Philippe Lang
+Examples+:
38 2 Jean-Philippe Lang
39 2 Jean-Philippe Lang
<pre>
40 2 Jean-Philippe Lang
GET /issues.xml
41 63 Go MAEDA
GET /issues.xml?issue_id=1
42 63 Go MAEDA
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 1 Jean-Philippe Lang
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 21 Alex Last
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 1 Jean-Philippe Lang
57 47 Jean-Baptiste Barth
To fetch issues for a date range (uncrypted filter is "><2012-03-01|2012-03-07") :
58 47 Jean-Baptiste Barth
GET /issues.xml?created_on=%3E%3C2012-03-01|2012-03-07
59 47 Jean-Baptiste Barth
60 47 Jean-Baptiste Barth
To fetch issues created after a certain date (uncrypted filter is ">=2012-03-01") :
61 47 Jean-Baptiste Barth
GET /issues.xml?created_on=%3E%3D2012-03-01
62 47 Jean-Baptiste Barth
63 47 Jean-Baptiste Barth
Or before a certain date (uncrypted filter is "<= 2012-03-07") :
64 47 Jean-Baptiste Barth
GET /issues.xml?created_on=%3C%3D2012-03-07
65 51 Jean-Philippe Lang
66 51 Jean-Philippe Lang
To fetch issues created after a certain timestamp (uncrypted filter is ">=2014-01-02T08:12:32Z") :
67 51 Jean-Philippe Lang
GET /issues.xml?created_on=%3E%3D2014-01-02T08:12:32Z
68 51 Jean-Philippe Lang
69 51 Jean-Philippe Lang
To fetch issues updated after a certain timestamp (uncrypted filter is ">=2014-01-02T08:12:32Z") :
70 51 Jean-Philippe Lang
GET /issues.xml?updated_on=%3E%3D2014-01-02T08:12:32Z
71 65 Stéphane Lavergne
72 65 Stéphane Lavergne
To fetch issues for which custom field 4 contains the substring "foo" :
73 65 Stéphane Lavergne
GET /issues.xml?cf_4=~foo
74 12 Robert Palmer
</pre>
75 1 Jean-Philippe Lang
76 1 Jean-Philippe Lang
+Response+:
77 1 Jean-Philippe Lang
78 59 Toshi MARUYAMA
<pre><code class="xml">
79 1 Jean-Philippe Lang
<?xml version="1.0" encoding="UTF-8"?>
80 1 Jean-Philippe Lang
<issues type="array" count="1640">
81 3 Christoph Witzany
  <issue>
82 3 Christoph Witzany
    <id>4326</id>
83 1 Jean-Philippe Lang
    <project name="Redmine" id="1"/>
84 1 Jean-Philippe Lang
    <tracker name="Feature" id="2"/>
85 1 Jean-Philippe Lang
    <status name="New" id="1"/>
86 1 Jean-Philippe Lang
    <priority name="Normal" id="4"/>
87 1 Jean-Philippe Lang
    <author name="John Smith" id="10106"/>
88 1 Jean-Philippe Lang
    <category name="Email notifications" id="9"/>
89 1 Jean-Philippe Lang
    <subject>
90 1 Jean-Philippe Lang
      Aggregate Multiple Issue Changes for Email Notifications
91 1 Jean-Philippe Lang
    </subject>
92 1 Jean-Philippe Lang
    <description>
93 1 Jean-Philippe Lang
      This is not to be confused with another useful proposed feature that
94 1 Jean-Philippe Lang
      would do digest emails for notifications.
95 1 Jean-Philippe Lang
    </description>
96 1 Jean-Philippe Lang
    <start_date>2009-12-03</start_date>
97 1 Jean-Philippe Lang
    <due_date></due_date>
98 1 Jean-Philippe Lang
    <done_ratio>0</done_ratio>
99 1 Jean-Philippe Lang
    <estimated_hours></estimated_hours>
100 1 Jean-Philippe Lang
    <custom_fields>
101 1 Jean-Philippe Lang
      <custom_field name="Resolution" id="2">Duplicate</custom_field>
102 1 Jean-Philippe Lang
      <custom_field name="Texte" id="5">Test</custom_field>
103 1 Jean-Philippe Lang
      <custom_field name="Boolean" id="6">1</custom_field>
104 1 Jean-Philippe Lang
      <custom_field name="Date" id="7">2010-01-12</custom_field>
105 1 Jean-Philippe Lang
    </custom_fields>
106 1 Jean-Philippe Lang
    <created_on>Thu Dec 03 15:02:12 +0100 2009</created_on>
107 1 Jean-Philippe Lang
    <updated_on>Sun Jan 03 12:08:41 +0100 2010</updated_on>
108 1 Jean-Philippe Lang
  </issue>
109 3 Christoph Witzany
  <issue>
110 3 Christoph Witzany
    <id>4325</id>
111 1 Jean-Philippe Lang
    ...
112 1 Jean-Philippe Lang
  </issue>
113 1 Jean-Philippe Lang
</issues>
114 59 Toshi MARUYAMA
</code></pre>
115 1 Jean-Philippe Lang
116 1 Jean-Philippe Lang
h2. Showing an issue
117 1 Jean-Philippe Lang
118 31 Ilya Kulakov
<pre>
119 43 Jean-Philippe Lang
GET /issues/[id].[format]
120 31 Ilya Kulakov
</pre>
121 31 Ilya Kulakov
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 43 Jean-Philippe Lang
  * @attachments@
128 43 Jean-Philippe Lang
  * @relations@
129 43 Jean-Philippe Lang
  * @changesets@
130 43 Jean-Philippe Lang
  * @journals@ - See [[Rest_IssueJournals|Issue journals]] for more information.
131 43 Jean-Philippe Lang
  * @watchers@ - Since 2.3.0
132 1 Jean-Philippe Lang
133 43 Jean-Philippe Lang
+Examples+:
134 43 Jean-Philippe Lang
135 43 Jean-Philippe Lang
<pre>
136 43 Jean-Philippe Lang
GET /issues/2.xml
137 43 Jean-Philippe Lang
GET /issues/2.json
138 43 Jean-Philippe Lang
139 43 Jean-Philippe Lang
GET /issues/2.xml
140 43 Jean-Philippe Lang
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 43 Jean-Philippe Lang
144 1 Jean-Philippe Lang
h2. Creating an issue
145 1 Jean-Philippe Lang
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 45 Jean-Philippe Lang
  * @tracker_id@
154 45 Jean-Philippe Lang
  * @status_id@
155 50 redmineservices .
  * @priority_id@
156 45 Jean-Philippe Lang
  * @subject@
157 45 Jean-Philippe Lang
  * @description@
158 45 Jean-Philippe Lang
  * @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 45 Jean-Philippe Lang
  * @parent_issue_id@ - ID of the parent issue
162 45 Jean-Philippe Lang
  * @custom_fields@ - See [[Rest_api#Working-with-custom-fields|Custom fields]]
163 45 Jean-Philippe Lang
  * @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 53 Matt Wiseley
  * @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 1 Jean-Philippe Lang
169 45 Jean-Philippe Lang
+Examples+:
170 1 Jean-Philippe Lang
171 59 Toshi MARUYAMA
<pre><code class="xml">
172 45 Jean-Philippe Lang
POST /issues.xml
173 45 Jean-Philippe Lang
<?xml version="1.0"?>
174 45 Jean-Philippe Lang
<issue>
175 45 Jean-Philippe Lang
  <project_id>1</project_id>
176 1 Jean-Philippe Lang
  <subject>Example</subject>
177 1 Jean-Philippe Lang
  <priority_id>4</priority_id>
178 45 Jean-Philippe Lang
</issue>
179 59 Toshi MARUYAMA
</code></pre>
180 1 Jean-Philippe Lang
<pre>
181 1 Jean-Philippe Lang
POST /issues.json
182 59 Toshi MARUYAMA
</pre>
183 59 Toshi MARUYAMA
<pre><code class="json">
184 45 Jean-Philippe Lang
{
185 45 Jean-Philippe Lang
  "issue": {
186 45 Jean-Philippe Lang
    "project_id": 1,
187 45 Jean-Philippe Lang
    "subject": "Example",
188 45 Jean-Philippe Lang
    "priority_id": 4
189 45 Jean-Philippe Lang
  }
190 45 Jean-Philippe Lang
}
191 59 Toshi MARUYAMA
</code></pre>
192 45 Jean-Philippe Lang
193 38 Jean-Philippe Lang
h2. Updating an issue
194 5 Damien Churchill
195 45 Jean-Philippe Lang
  PUT /issues/[id].[format]
196 5 Damien Churchill
197 45 Jean-Philippe Lang
+Parameters+:
198 5 Damien Churchill
199 45 Jean-Philippe Lang
* @issue@ - A hash of the issue attributes
200 27 Stéphane Schoorens
201 45 Jean-Philippe Lang
  * @project_id@
202 45 Jean-Philippe Lang
  * @tracker_id@
203 45 Jean-Philippe Lang
  * @status_id@
204 45 Jean-Philippe Lang
  * @subject@
205 45 Jean-Philippe Lang
  * ...
206 45 Jean-Philippe Lang
  * @notes@ - Comments about the update
207 54 Matt Wiseley
  * @private_notes@ - true if notes are private
208 1 Jean-Philippe Lang
209 1 Jean-Philippe Lang
Attachments can be added when you update an issue, see [[Rest_api#Attaching-files|Attaching files]].
210 1 Jean-Philippe Lang
211 1 Jean-Philippe Lang
+Examples+:
212 1 Jean-Philippe Lang
213 45 Jean-Philippe Lang
<pre>
214 45 Jean-Philippe Lang
PUT /issues/[id].xml
215 59 Toshi MARUYAMA
</pre>
216 59 Toshi MARUYAMA
217 59 Toshi MARUYAMA
<pre>
218 59 Toshi MARUYAMA
<code class="xml">
219 45 Jean-Philippe Lang
<?xml version="1.0"?>
220 1 Jean-Philippe Lang
<issue>
221 1 Jean-Philippe Lang
  <subject>Subject changed</subject>
222 1 Jean-Philippe Lang
  <notes>The subject was changed</notes>
223 45 Jean-Philippe Lang
</issue>
224 59 Toshi MARUYAMA
</code></pre>
225 45 Jean-Philippe Lang
226 45 Jean-Philippe Lang
<pre>
227 45 Jean-Philippe Lang
PUT /issues/[id].json
228 59 Toshi MARUYAMA
</pre>
229 59 Toshi MARUYAMA
230 59 Toshi MARUYAMA
<pre><code class="json">
231 45 Jean-Philippe Lang
{
232 45 Jean-Philippe Lang
  "issue": {
233 45 Jean-Philippe Lang
    "subject": "Subject changed",
234 45 Jean-Philippe Lang
    "notes": "The subject was changed"
235 45 Jean-Philippe Lang
  }
236 1 Jean-Philippe Lang
}
237 45 Jean-Philippe Lang
</pre>
238 44 Jean-Philippe Lang
239 44 Jean-Philippe Lang
h2. Deleting an issue
240 44 Jean-Philippe Lang
241 45 Jean-Philippe Lang
  DELETE /issues/[id].[format]
242 44 Jean-Philippe Lang
243 46 Jean-Philippe Lang
h2. Adding a watcher 
244 1 Jean-Philippe Lang
245 46 Jean-Philippe Lang
_Added in 2.3.0_
246 46 Jean-Philippe Lang
247 44 Jean-Philippe Lang
  POST /issues/[id]/watchers.[format]
248 44 Jean-Philippe Lang
249 44 Jean-Philippe Lang
+Parameters+:
250 44 Jean-Philippe Lang
251 44 Jean-Philippe Lang
* @user_id@ (required): id of the user to add as a watcher
252 44 Jean-Philippe Lang
253 1 Jean-Philippe Lang
h2. Removing a watcher
254 46 Jean-Philippe Lang
255 46 Jean-Philippe Lang
_Added in 2.3.0_
256 1 Jean-Philippe Lang
257 1 Jean-Philippe Lang
  DELETE /issues/[id]/watchers/[user_id].[format]
258 1 Jean-Philippe Lang
259 1 Jean-Philippe Lang
+Parameters+: _none_