Rest Issues » History » Version 54

Matt Wiseley, 2014-12-13 18:21
Added additionally supported private_notes to PUT parameters

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