All comment endpoints are available off of their parent issue.
Creating Comments
This endpoint creates new comments for a project’s issues.
How it works…
- Fetch the project detail.
- Fetch the issue detail.
- Post the new comment.
- Process the result object or error.
1. Fetch the Project Details
In order to comment on a project’s issue, you’ll need to find the relevant project and issue objects in the API first. 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.
1 {
2 "projects": [
3 {
4 "name": "Daniel's Test Kitchen",
5 "archived": false,
6 "primary_company_name": "Example Company",
7 "url": "https://example.sifterapp.com/projects/1",
8 "issues_url": "https://example.sifterapp.com/projects/1/issues",
9 "milestones_url": "https://example.sifterapp.com/projects/1/milestones",
10 "api_url": "https://example.sifterapp.com/api/projects/1",
11 "api_issues_url": "https://example.sifterapp.com/api/projects/1/issues",
12 "api_milestones_url": "https://example.sifterapp.com/api/projects/1/milestones",
13 "api_categories_url": "https://example.sifterapp.com/api/projects/1/categories",
14 "api_people_url": "https://example.sifterapp.com/api/projects/1/people",
15 "api_new_issue_email_address": "[email protected]"
16 },
17 {
18 "name": "example.com",
19 "archived": false,
20 "primary_company_name": "Example Sister Company",
21 "url": "https://example.sifterapp.com/projects/2",
22 "issues_url": "https://example.sifterapp.com/projects/2/issues",
23 "milestones_url": "https://example.sifterapp.com/projects/2/milestones",
24 "api_url": "https://example.sifterapp.com/api/projects/2",
25 "api_issues_url": "https://example.sifterapp.com/api/projects/2/issues",
26 "api_milestones_url": "https://example.sifterapp.com/api/projects/2/milestones",
27 "api_categories_url": "https://example.sifterapp.com/api/projects/2/categories",
28 "api_people_url": "https://example.sifterapp.com/api/projects/2/people",
29 "api_new_issue_email_address": "[email protected]"
30 }
31 ]
32 }2. Fetch the Issue Details
Once you’ve listed your account’s projects, you can select a project and use its api_issues_url to find an issue you’d like to comment on. In this case, dig in on the “Daniel’s Test Kitchen” project to find an issue worth commenting on.
1 {
2 "issues": [
3 {
4 "number": 953,
5 "subject": "comment on me please",
6 "description": "please",
7 "created_at": "2018-03-01T22:26:01Z",
8 "updated_at": "2018-03-07T17:24:57Z",
9 "comment_count": 9,
10 "attachment_count": 0,
11 "opener_name": "Daniel Pritchett",
12 "opener_email": "[email protected]",
13 "category_name": null,
14 "milestone_name": null,
15 "assignee_name": "Unassigned",
16 "assignee_email": null,
17 "priority": "Normal",
18 "status": "Open",
19 "api_url": "https://example.sifterapp.com/api/projects/1/issues/4327285",
20 "url": "https://example.sifterapp.com/projects/1/issues/4327285"
21 },
22 {
23 "number": 945,
24 "subject": "can we make issues?",
25 "description": "yes!",
26 "created_at": "2018-01-19T05:20:59Z",
27 "updated_at": "2018-03-02T02:52:45Z",
28 "comment_count": 13,
29 "attachment_count": 0,
30 "opener_name": "Daniel Pritchett",
31 "opener_email": "[email protected]",
32 "category_name": null,
33 "milestone_name": null,
34 "assignee_name": "Unassigned",
35 "assignee_email": null,
36 "priority": "Normal",
37 "status": "Open",
38 "api_url": "https://example.sifterapp.com/api/projects/1/issues/4290973",
39 "url": "https://example.sifterapp.com/projects/1/issues/4290973"
40 }
41 ]
42 }3. Post the New Comment
Pick the first issue from the previous section, the one that’s begging for a new comment. Take its api_url and set up a POST action to create a new comment on that issue.
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
body: the main text of the comment.
Optional
internal: Set this totrueif the comment should only be visible to members of the Sifter account’s primary organization.
The endpoint for posting the new issue is:
/api/projects/{project_id}/issues/{issue_id}
A successful issue create request might look like this:
curl -X POST \
https://example.sifterapp.com/api/projects/1/issues/4327285 \
-H 'x-sifter-token: 39blahblahblahtokenabcdef123' \
-F 'body=FIRST POST'4. Process the Result or Error
After you post an comment, there’s two possible outcomes. Either the comment 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 fetched a single comment:
1 {
2 "comment": {
3 "body": "FIRST POST",
4 "created_at": "2018-03-07T20:26:34Z",
5 "updated_at": "2018-03-07T20:26:34Z",
6 "milestone_name": null,
7 "assignee_name": "Unassigned",
8 "assignee_email": null,
9 "opener_email": "[email protected]",
10 "commenter_email": "[email protected]",
11 "priority": "Normal",
12 "status": "Open",
13 "project": "Daniel's Test Kitchen",
14 "opener": "Daniel Pritchett",
15 "commenter": "Daniel Pritchett",
16 "category": null,
17 "attachments": []
18 }
19 }Error Response
If an invalid comment is posted, an error response is returned with error messages associated with the relevant field:
1 {
2 "error": "Invalid comment",
3 "detail": {
4 "base": [
5 "You need to make a change to the issue or add new information before we can update the issue."
6 ]
7 }
8 }