Rest Issues » History » Version 47

Jean-Baptiste Barth, 2013-05-06 23:30
Add some example about that manipulation and encode filter operators (else the request doesn't work because rails cannot parse the query string)

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