Rest Issues » History » Version 57

Go MAEDA, 2017-05-01 14:16
Filter by parent_id is supported as of Redmine 3.1.0

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