Project

General

Profile

Rest Issues » History » Version 56

Rafael Dantas, 2017-01-19 20:22
Add 'issue_id' optional filters

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