Project

General

Profile

Rest Issues » History » Version 69

Mischa The Evil, 2021-05-23 07:15
Fixups after page versions 61, 62, 64, 67 and 68.

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