Project

General

Profile

Rest Issues » History » Version 60

Matteo Steccolini, 2018-06-05 12:43
GET /issues.xml?issue_id=1 doesn't work in 3.4.4, changing to GET /issues.xml?id=1

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