TaskComments - Huddle/huddle-apis GitHub Wiki

Summary

Status

Operation
Retrieve a comment
Retrieve all comments on a task
Add a comment to a task
Add an approval comment to a task
Delete a comment

Operations

Retrieve a comment

Link relations

Name Description Methods
self The URI of the Comment. GET
parent The URI of the Task. GET
delete The URI to delete the Comment. DELETE

Example

Request

GET /tasks/12345/comments/456 HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty

JSON Response

If successful, this method will return a response with an OK status code. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
{
    "links": [
        { "rel": "self", "href": "..." },
        { "rel": "parent", "href": "..." },
        { "rel": "delete", "href": "..." }
    ],
    "content": "This is a comment for the task.",
    "actors": [{
        "name": "Peter Gibson",
        "email": "[email protected]",
        "rel": "owner",
        "links": [
            { "rel": "self", "href": ".." },
            { "rel": "avatar", "href": "..", "type": "image/jpeg" },
            { "rel": "alternate", "href": "..", "type": "text/html" }
        ]
    }]
}

XML Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
<comment>
    <link rel="self" href="..." />
    <link rel="parent" href="..." />
    <link rel="delete" href="..." />
    <content>This is a comment for the task.</content>
    <created>2007-10-10T09:02:17Z</created>
    <actor name="Peter Gibson" email="[email protected]" rel="owner">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpeg" />
        <link rel="alternate" href="..." type="text/html" />
    </actor>
</comment>

Error Responses

Case Response Code Error Code
Comment does not exist 404 Not Found CommentNotFound
Comment is deleted 404 Not Found CommentDeleted
Task does not exist 404 Not Found TaskNotFound
Task is deleted 404 Not Found TaskDeleted
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is deleted 404 Not Found WorkspaceDeleted

Retrieve all comments on a task

This is limited to your 500 most recent comments.

Parameter Default value Additional notes
pagesize 500 Minimum: 1, Maximum: 500
skipitems 0

Link relations

Name Description Methods
self The URI of the Comments on the Task. GET
parent The URI of the Task. GET
create The URI to add a Comment to the Task. POST
current The URI of the current page. GET
first The URI of the first page. GET
next The URI of the next page. GET
prev The URI of the previous page. GET

Example

Request

GET /tasks/12345/comments HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty

JSON Response

If successful, this method will return a response with an OK status code. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
{
    "links": [
        { "rel": "self", "href": "..." },
        { "rel": "parent", "href": "..." },
        { "rel": "create", "href": "..." },
        { "rel": "current", "href": "..." },
        { "rel": "next", "href": "..." }
    ],
    "comments": [{
        "links": [
            { "rel": "self", "href": "..." },
            ... other comment links ...
        ],
        ... other comment elements ...
    }]
}

XML Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
<comments>
    <link rel="self" href="..." />
    <link rel="parent" href="..." />
    <link rel="create" href="..." />
    <items>
        <comment>
            <link rel="self" href="..."/>
            ... other comment elements ...
        </comment>
    </items>
</comments>

Error Responses

Case Response Code Error Code
Task does not exist 404 Not Found TaskNotFound
Task is deleted 404 Not Found TaskDeleted
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is deleted 404 Not Found WorkspaceDeleted

Add a comment to a task

Example

JSON Request

POST /tasks/12345/comments HTTP/1.1
Content-Type: application/json
Authorization: OAuth2 frootymcnooty/vonbootycherooty
{
    "content": "This is a comment for the task.",
}

XML Request

POST /tasks/12345/comments HTTP/1.1
Content-Type: application/xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty
<comment>
    <content>This is a comment for the task.</content>
</comment>

Response

If successful, this method will return an empty response with a Created status code and a Location header containing the URI of the created comment. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 201 Created
Location: /tasks/12345/comments/456

Error Responses

Case Response Code Error Code
Content is missing or empty 400 Bad Request Invalid
Task does not exist 404 Not Found TaskNotFound
Task is deleted 404 Not Found TaskDeleted
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is deleted 404 Not Found WorkspaceDeleted

Add an approval comment to a task

Request

Parameter Value
approval? "Complete" / "Rejected" / null

Example

JSON Request

POST /tasks/12345/comments HTTP/1.1
Content-Type: application/json
Authorization: OAuth2 frootymcnooty/vonbootycherooty
{
    "content": "This is a comment for the task.",
    "approval": "Rejected"
}
<comment>
    <content>This is a comment for the task.</content>
    <approval>Rejected</approval>
</comment>

Response

If successful, this method will return an empty response with a Created status code and a Location header containing the URI of the created comment. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 201 Created
Location: /tasks/12345/comments/456

Delete a comment

Example

Request

DELETE /tasks/12345/comments/456 HTTP/1.1
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

If successful, this method will return an empty response with a No Content status code. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 204 No Content

Error Responses

Case Response Code Error Code
Comment does not exist 404 Not Found CommentNotFound
Comment is deleted 409 Conflict CommentDeleted
Task does not exist 404 Not Found TaskNotFound
Task is deleted 404 Not Found TaskDeleted
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is deleted 404 Not Found WorkspaceDeleted
User is not Comment Owner or Workspace Manager 403 Forbidden InsufficientPermissions
⚠️ **GitHub.com Fallback** ⚠️