Rest Issues » History » Revision 49
Revision 48 (Filou Centrinov, 2013-05-21 02:01) → Revision 49/70 (Maarten Verwijs, 2013-06-19 23:28)
h1. Issues
{{>toc}}
h2. Listing issues
GET /issues.[format]
Returns a paginated list of issues. By default, it returns open issues only.
+Parameters+:
* @offset@: skip this number of issues in response (optional)
* @limit@: number of issues per page (optional)
* @sort@: column to sort with. Append @:desc@ to invert the order.
Optional filters:
* @project_id@: get issues from the project with the given id, where id is either project id or project identifier
* @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.
* @tracker_id@: get issues from the tracker with the given id
* @status_id@: get issues with the given status id only. Possible values: @open@, @closed@, @*@ to get open and closed issues, status id
* @assigned_to_id@: get issues which are assigned to the given user id
* @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.)
* ...
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.
+Examples+:
<pre>
GET /issues.xml
GET /issues.xml?project_id=2
GET /issues.xml?project_id=2&tracker_id=1
GET /issues.xml?assigned_to_id=6
GET /issues.xml?status_id=closed
GET /issues.xml?status_id=*
GET /issues.xml?cf_1=abcdef
GET /issues.xml?sort=category:desc,updated_on
Paging example:
GET /issues.xml?offset=0&limit=100
GET /issues.xml?offset=100&limit=100
To fetch issues for a date range (uncrypted filter is "><2012-03-01|2012-03-07") :
GET /issues.xml?created_on=%3E%3C2012-03-01|2012-03-07
To fetch issues created after a certain date (uncrypted filter is ">=2012-03-01") :
GET /issues.xml?created_on=%3E%3D2012-03-01
Or before a certain date (uncrypted filter is "<= 2012-03-07") :
GET /issues.xml?created_on=%3C%3D2012-03-07
</pre>
+Response+:
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<issues type="array" count="1640">
<issue>
<id>4326</id>
<project name="Redmine" id="1"/>
<tracker name="Feature" id="2"/>
<status name="New" id="1"/>
<priority name="Normal" id="4"/>
<author name="John Smith" id="10106"/>
<category name="Email notifications" id="9"/>
<subject>
Aggregate Multiple Issue Changes for Email Notifications
</subject>
<description>
This is not to be confused with another useful proposed feature that
would do digest emails for notifications.
</description>
<start_date>2009-12-03</start_date>
<due_date></due_date>
<done_ratio>0</done_ratio>
<estimated_hours></estimated_hours>
<custom_fields>
<custom_field name="Resolution" id="2">Duplicate</custom_field>
<custom_field name="Texte" id="5">Test</custom_field>
<custom_field name="Boolean" id="6">1</custom_field>
<custom_field name="Date" id="7">2010-01-12</custom_field>
</custom_fields>
<created_on>Thu Dec 03 15:02:12 +0100 2009</created_on>
<updated_on>Sun Jan 03 12:08:41 +0100 2010</updated_on>
</issue>
<issue>
<id>4325</id>
...
</issue>
</issues>
</pre>
h2. Showing an issue
<pre>
GET /issues/[id].[format]
</pre>
+Parameters+:
* @include@: fetch associated data (optional, use comma to fetch multiple associations). Possible values:
* @children@
* @attachments@
* @relations@
* @changesets@
* @journals@ - See [[Rest_IssueJournals|Issue journals]] for more information.
* @watchers@ - Since 2.3.0
+Examples+:
<pre>
GET /issues/2.xml
GET /issues/2.json
GET /issues/2.xml
GET /issues/2.xml?include=attachments
GET /issues/2.xml?include=attachments,journals
</pre>
h2. Creating an issue
POST /issues.[format]
+Parameters+:
* @issue@ - A hash of the issue attributes:
* @project_id@
* @tracker_id@
* @status_id@
* @subject@
* @description@
* @category_id@
* @fixed_version_id@ - ID of the Target Versions (previously called 'Fixed Version' and still referred to as such in the API)
* @assigned_to_id@ - ID of the user to assign the issue to (currently no mechanism to assign by name)
* @parent_issue_id@ - ID of the parent issue
* @custom_fields@ - See [[Rest_api#Working-with-custom-fields|Custom fields]]
* @watcher_user_ids@ - Array of user ids to add as watchers (since 2.3.0)
Attachments can be added when you create an issue, see [[Rest_api#Attaching-files|Attaching files]].
+Examples+:
<pre>
POST /issues.xml
<?xml version="1.0"?>
<issue>
<project_id>1</project_id>
<subject>Example</subject>
<priority_id>4</priority_id>
</issue>
</pre>
<pre>
POST /issues.json
{
"issue": {
"project_id": 1,
"subject": "Example",
"priority_id": 4
}
}
</pre>
h2. Updating an issue
PUT /issues/[id].[format]
+Parameters+:
* @issue@ - A hash of the issue attributes
* @project_id@
* @tracker_id@
* @status_id@
* @subject@
* ...
* @notes@ - Comments about the update
Attachments can be added when you update an issue, see [[Rest_api#Attaching-files|Attaching files]].
+Examples+:
<pre>
PUT /issues/[id].xml
<?xml version="1.0"?>
<issue>
<subject>Subject changed</subject>
<notes>The subject was changed</notes>
</issue>
</pre>
<pre>
PUT /issues/[id].json
{
"issue": {
"subject": "Subject changed",
"notes": "The subject was changed"
}
}
</pre>
h2. Deleting an issue
DELETE /issues/[id].[format]
h2. Adding a watcher
_Added in 2.3.0_
POST /issues/[id]/watchers.[format]
+Parameters+:
* @user_id@ (required): id of the user to add as a watcher
h2. Removing a watcher
_Added in 2.3.0_
DELETE /issues/[id]/watchers/[user_id].[format]
+Parameters+: _none_