Project

General

Profile

Rest Issues » History » Version 52

davi vidal, 2014-02-06 15:44

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