This is the newer, REST-based version of this API. If you are maintaining an older application, it might be using the legacy, non-RESTful version of this API, which can be found documented here.
The comments API is identical for Messages, Milestones, and Todo Items, the only difference being the resource named in URL prefix. This can be one of "posts", "milestones", or "todo_items", respectively. In the documentation that follows, the generic "#{resource}" should be replaced with the resource you are acting on.
Return a list of the 50 most recent comments associated with the specified resource, where the resource named in the URL can be one of posts, milestones, or todo_items. For example, to fetch the most recent comments for the todo item with an id of 1, you would use the path: /todo_items/1/comments.xml.
The root <comments> element has a “count” attribute specifying the total number of comments for the resource. If there are older comments not included in the response, the <comments> element will also have a “continued-at” attribute specifying the path where the next oldest 50 comments can be retrieved.
<comments count="50" continued-at="...">
<comment>
...
</comment>
<comment>
...
</comment>
...
</comments>
Retrieve a specific comment by its id.
<comment>
...
</comment>
Returns a blank XML “template” for a single comment record, indicating which fields may be submitted to create a new comment. It will also return a custom HTTP header (X-Create-Action) indicating where and how the data may be submitted.
<comment>
...
</comment>
Create a new comment, associating it with a specific resource, where the resource named in the URL can be one of posts, milestones, or todo_items. For example, to create a comment for the milestone with an ID of 1, you would use the path: /milestones/1/comments.xml.
<comment>
<body>#{body}</body>
</comment>
Returns HTTP status code 201 (“Created”) on success, with the Location header set to the URL for the new comment. The new comment’s ID can be extracted from that URL. On failure, a non-200 status code will be returned, possibly with error information in XML format as the response’s content.
Returns an XML “template” for a single comment record, prefilled with the existing values for that record, and ready to be resubmitted via the “update comment” action. It will also return a custom HTTP header (X-Update-Action) indicating where and how the data may be submitted.
<comment>
...
</comment>
Update a specific comment. This can be used to edit the content of an existing comment.
<request>
<comment>
<body>#{body}</body>
</comment>
</request>
Returns HTTP status code 200 on success, or any other code (and possibly error information in XML format) on error.
Delete the comment with the given ID.
Returns HTTP status code 200 on success.