Project

General

Profile

Rest Issues » History » Version 50

redmineservices ., 2013-07-04 19:06
priority_id added to creating an issue

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