All issue endpoints are available off of their parent project.
Project Issue Listing
This endpoint provides a listing of all the issues for the specified project.
/api/projects/{project_id}/issues
1 {
2 "issues": [
3 {
4 "number": 57,
5 "category_name": "Enhancement",
6 "priority": "Trivial",
7 "subject": "Donec vel neque",
8 "description": "Nam id libero quis ipsum feugiat elementum. Vivamus vitae mauris ut ipsum mattis malesuada. Sed vel massa. Mauris lobortis. Nunc egestas, massa id scelerisque dapibus, urna mi accumsan purus, vel aliquam nunc sapien eget nisi. Quisque vitae nibh. Proin interdum mollis leo. Fusce sed nisi. Integer ut tortor.",
9 "milestone_name": null,
10 "opener_name": "Adam Keys",
11 "opener_email": "[email protected]",
12 "assignee_name": "Garrett Dimon",
13 "assignee_email": "[email protected]",
14 "status": "Open",
15 "comment_count": 2,
16 "attachment_count": 1,
17 "created_at": "2010/05/16 19:13:16 +0000",
18 "updated_at": "2010/05/16 19:13:16 +0000",
19 "url": "https://example.sifterapp.com/projects/1/issues/5",
20 "api_url": "https://example.sifterapp.com/api/projects/1/issues/5"
21 },
22 {
23 "number": 63,
24 "category_name": "Bug",
25 "priority": "Trivial",
26 "subject": "Sed lectus nunc, egestas tincidunt",
27 "description": "Proin dictum dignissim metus. Vivamus vel risus sed augue venenatis sodales. Quisque tempus dictum lorem. Sed a turpis eu turpis lobortis pellentesque. Nunc sem mi, ullamcorper non, dignissim eu, pellentesque eget, justo. Donec mollis neque quis tortor. In hac habitasse platea dictumst. Mauris at velit non erat scelerisque iaculis.",
28 "milestone_name": null,
29 "opener_name": "Adam Keys",
30 "opener_email": "[email protected]",
31 "assignee_name": null,
32 "assignee_email": null,
33 "status": "Open",
34 "comment_count": 0,
35 "attachment_count": 0,
36 "created_at": "2010/05/16 19:13:16 +0000",
37 "updated_at": "2010/05/16 19:13:16 +0000",
38 "url": "https://example.sifterapp.com/projects/1/issues/6",
39 "api_url": "https://example.sifterapp.com/api/projects/1/issues/6"
40 }
41 ],
42 "page": 1,
43 "per_page": 100,
44 "total_pages": 2,
45 "next_page_url": "https://example.sifterapp.com/api/projects/1/issues?per_page=10&page=1",
46 "previous_page_url": null
47 }Pagination
Issue listings are paginated. Each page includes 100 issues. Use the page parameter to specify the offset to use when paging through results.
/api/projects/{project_id}/issues?per_page=5&page=2
Sorting & Filtering Issues
You can also limit the results of the issue listing to specific statuses or priorities using the s and p query string values respectively.
The following example would only return open issues.
/api/projects/{project_id}/issues?s=1
And this example would only return critical issues.
/api/projects/{project_id}/issues?p=1
You can pass multiple values for statuses and priorities by hyphenating them. For example, the following request would only return critical or high priority issues that are either open or reopened.
/api/projects/{project_id}/issues?p=1-2&s=1-2
Searching Issues
You can search issues using the q parameter. For example, you could search for the word “api”.
/api/projects/{project_id}/issues?q=api
Issue Detail
This endpoint provides the detail for a specific issue.
/api/projects/{project_id}/issues/{issue_id}
1 {
2 "issue": {
3 "number": 63,
4 "subject": "Sed lectus nunc, egestas tincidunt",
5 "description": "Proin dictum dignissim metus. Vivamus vel risus sed augue venenatis sodales. Quisque tempus dictum lorem. Sed a turpis eu turpis lobortis pellentesque. Nunc sem mi, ullamcorper non, dignissim eu, pellentesque eget, justo. Donec mollis neque quis tortor. In hac habitasse platea dictumst. Mauris at velit non erat scelerisque iaculis.",
6 "priority": "Trivial",
7 "status": "Open",
8 "category_name": "Bug",
9 "milestone_name": null,
10 "opener_name": "Adam Keys",
11 "opener_email": "[email protected]",
12 "assignee_name": null,
13 "assignee_email": null,
14 "comment_count": 0,
15 "attachment_count": 1,
16 "created_at": "2010/05/16 19:13:16 +0000",
17 "updated_at": "2010/05/16 19:13:16 +0000",
18 "url": "https://example.sifterapp.com/projects/1/issues/5",
19 "api_url": "https://example.sifterapp.com/api/projects/1/issues/5",
20 "comments": [
21 {
22 "body": "Proin dictum dignissim metus. Vivamus vel risus sed augue venenatis sodales. Quisque tempus dictum lorem. Sed a turpis eu turpis lobortis pellentesque. Nunc sem mi, ullamcorper non, dignissim eu, pellentesque eget, justo. Donec mollis neque quis tortor. In hac habitasse platea dictumst. Mauris at velit non erat scelerisque iaculis.",
23 "priority": "Trivial",
24 "status": "Open",
25 "category": "Bug",
26 "commenter": "Adam Keys",
27 "commenter_email": "[email protected]",
28 "opener": "Adam Keys",
29 "opener_email": "[email protected]",
30 "project": "Rhino",
31 "milestone_name": null,
32 "assignee_name": null,
33 "assignee_email": null,
34 "created_at": "2010/05/16 19:13:16 +0000",
35 "updated_at": "2010/05/16 19:13:16 +0000",
36 "attachments": [
37 {
38 "filename": "1.png",
39 "size": 16895,
40 "height": 294,
41 "width": 320,
42 "url": "http://example.sifterapp.com/attachments/1",
43 "thumb_url": "https://example.s3.amazonaws.com/attachments/1/1_thumb.png?AWSAccessKeyId=123456&Signature=123456&Expires=1351808613"
44 }
45 ]
46 }
47 ]
48 }
49 }Creating Issues
This endpoint creates new issues for a project.
How it works…
- Fetch the project detail, including all the metadata.
- Post the new issue using the parameters from the project’s details.
- Process the result object or error.
1. Fetch the Project Details
In order to create an issue, you’ll need to obtain all of the available assigness, categories, milestones, statuses, and priorities for your project. You’ll probably want to cache this data using the ETag to periodically refresh your cache.
Let’s look at an example of fetching a project’s data in Sifter. You’ll
want to request all the metadata for a project. We can do so with the include
parameter. It’s simplest to use include=all, like so:
1 {
2 "project": {
3 "name": "Sifter",
4 "archived": false,
5 "primary_company_name": "Next Update",
6 "url": "http://example.sifterapp.com/projects/1",
7 "issues_url": "http://example.sifterapp.com/projects/1/issues",
8 "milestones_url": "http://example.sifterapp.com/projects/1/milestones",
9 "api_url": "http://example.sifterapp.com/api/projects/1",
10 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues",
11 "api_milestones_url": "http://example.sifterapp.com/api/projects/1/milestones",
12 "api_categories_url": "http://example.sifterapp.com/api/projects/1/categories",
13 "api_people_url": "http://example.sifterapp.com/api/projects/1/people",
14 "milestones": [
15 {
16 "name": "Alpha",
17 "due_date": "2015-05-01",
18 "active": true,
19 "issues_url": "http://example.sifterapp.com/projects/1/issues?m=1",
20 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?m=1"
21 },
22 {
23 "name": "Beta",
24 "due_date": "2015-05-15",
25 "active": true,
26 "issues_url": "http://example.sifterapp.com/projects/1/issues?m=2",
27 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?m=2"
28 },
29 {
30 "name": "Live",
31 "due_date": "2015-05-30",
32 "active": true,
33 "issues_url": "http://example.sifterapp.com/projects/1/issues?m=3",
34 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?m=3"
35 }
36 ],
37 "categories": [
38 {
39 "name": "Backend",
40 "issues_url": "http://example.sifterapp.com/projects/1/issues?c=1",
41 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?c=1"
42 },
43 {
44 "name": "Frontend",
45 "issues_url": "http://example.sifterapp.com/projects/1/issues?c=2",
46 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?c=2"
47 },
48 {
49 "name": "Server",
50 "issues_url": "http://example.sifterapp.com/projects/1/issues?c=3",
51 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?c=3"
52 },
53 {
54 "name": "Database",
55 "issues_url": "http://example.sifterapp.com/projects/1/issues?c=4",
56 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?c=4"
57 }
58 ],
59 "people": [
60 {
61 "username": "akeys",
62 "first_name": "Adam",
63 "last_name": "Keys",
64 "email": "[email protected]",
65 "issues_url": "http://example.sifterapp.com/projects/1/issues?a=2",
66 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?a=2"
67 },
68 {
69 "username": "gdimon",
70 "first_name": "Garrett",
71 "last_name": "Dimon",
72 "email": "[email protected]",
73 "issues_url": "http://example.sifterapp.com/projects/1/issues?a=1",
74 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?a=1"
75 },
76 {
77 "username": "keithmjacobs",
78 "first_name": "Keith",
79 "last_name": "Jacobs",
80 "email": "[email protected]",
81 "issues_url": "http://example.sifterapp.com/projects/1/issues?a=3",
82 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?a=3"
83 },
84 {
85 "username": "tdimon",
86 "first_name": "Tyler",
87 "last_name": "Dimon",
88 "email": "[email protected]",
89 "issues_url": "http://example.sifterapp.com/projects/1/issues?a=4",
90 "api_issues_url": "http://example.sifterapp.com/api/projects/1/issues?a=4"
91 }
92 ],
93 "priorities": [
94 {
95 "name": "Critical"
96 },
97 {
98 "name": "High"
99 },
100 {
101 "name": "Normal"
102 },
103 {
104 "name": "Low"
105 },
106 {
107 "name": "Trivial"
108 }
109 ],
110 "statuses": [
111 {
112 "name": "Open"
113 },
114 {
115 "name": "Reopened"
116 },
117 {
118 "name": "Resolved"
119 },
120 {
121 "name": "Closed"
122 }
123 ]
124 }
125 }2. Post the New Issue and Parameters
Once you’ve grabbed all of the relevant options for a project, you can use this to prompt a user for the relevant choices to create an issue or otherwise use it to automatically generate an issue by submitting the relevant parameters.
Parameters
The parameters the create API takes are subject, body, assignee_name,
priority_name, milestone_name, and category_name.
Subject is required, the rest are optional. For all of the _name
parameters, you should use the name attribute for the object in question.
For example, priority_name should be one of “Critical”, “High”, “Normal”,
“Low”, or “Trivial”.
Required
subject: the headline, subject of the issue
Optional
body: the detailed, body text of the issue;priority_name: The priority for the issue, as defined in the priorities metadata; optional (Defaults to ‘Normal’ if left blank.)assignee_name: the user the issue should be assigned to, as defined in the team members metadata (Defaults to ‘Unassigned’ if blank.)category_name: The category for the issue, as defined by the categories metadatamilestone_name: The milestone to place the issue in, as defined by the milestones metadata. In the event that multiple milestones have the same name, Sifter will choose from the milestones that have the same name and use the one with the earliest due date.
In general, we recommend not setting a status value at all. It is provided as an option to aid in importing issues from other tools.
The endpoint for posting the new issue is:
/api/projects/{project_id}/issues
A successful issue create request might look like this:
curl -X "POST" "http://example.sifterapp.com/api/projects/1/issues" \
-H "X-Sifter-Token: 343b1b831066a40e308e0af92e0f06f0" \
-H "Accept: application/json" \
-d "body=Could you please make it slightly more blue just slightly" \
-d "priority_name=Normal" \
-d "subject=Too blue" \
-d "category_name=Backend" \
-d "assignee_name=akeys" \
-d "milestone_name=Bug Fixes"3. Process the Result or Error
After you post an issue, there’s two possible outcomes. Either the issue is accepted and created, or Sifter will return an error response.
Successful Response with Result Object
On success, the API returns the same JSON as if you fetch a single issue:
1 {
2 "issue": {
3 "number": 2412,
4 "subject": "Too blue",
5 "description": "Could you please make it slightly more blue just slightly",
6 "created_at": "2015-02-04T02:34:48Z",
7 "updated_at": "2015-02-04T02:34:48Z",
8 "comment_count": -1,
9 "attachment_count": 0,
10 "opener_name": "Adam Keys",
11 "opener_email": "[email protected]",
12 "category_name": "Backend",
13 "milestone_name": "Bug Fixes",
14 "assignee_name": "Adam Keys",
15 "assignee_email": "[email protected]",
16 "priority": "Normal",
17 "status": "Open",
18 "api_url": "http://example.sifterapp.com/api/projects/1/issues/1027641",
19 "url": "http://example.sifterapp.com/projects/1/issues/1027641",
20 "comments": [
21 {
22 "body": "Could you please make it slightly more blue just slightly",
23 "created_at": "2015-02-04T02:34:48Z",
24 "updated_at": "2015-02-04T02:34:48Z",
25 "milestone_name": "Bug Fixes",
26 "assignee_name": "Adam Keys",
27 "assignee_email": "[email protected]",
28 "opener_email": "[email protected]",
29 "commenter_email": "[email protected]",
30 "priority": "Normal",
31 "status": "Open",
32 "project": "Sifter",
33 "opener": "Adam Keys",
34 "commenter": "Adam Keys",
35 "category": "Backend",
36 "attachments": []
37 }
38 ]
39 }
40 }Error Response
If an invalid issue is posted, an error response is returned with error messages associated with the relevant field:
1 {
2 "error": "Invalid issue",
3 "detail": {
4 "subject": [
5 "Subject can't be blank"
6 ],
7 "milestone_name": [
8 "Milestone named Bug Fixes111 not found"
9 ]
10 }
11 }