Tasks on Documents - Huddle/huddle-apis GitHub Wiki
Tasks attached to Document
Summary
APIs to return Tasks for a document, where that document has been attached to the Task.
Status
| Operation |
|---|
| Retrieve the to-do collection for attached document |
| Create a to-do and attach the document |
| Delete a to-do against the document |
Operations
Retrieve To-dos attached Document
This endpoint returns the title, description, assignments, status, start and due dates for all To-do Tasks that have been created for a Document.
Get Request
GET /tasks/document/123/todo HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty
Get Response
HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
{
"tasks": [
{
"title": "The title of the To-do task",
"description": "The description, if supplied, of the to-do task",
"status": "InProgress",
"plannedStartDate": "2019-02-28",
"dueDate": "2019-03-01",
"createdDate": "Thu, 28 Mar 2019 12:36:52 GMT",
"updatedDate": "Thu, 29 Mar 2019 13:36:52 GMT",
"actors": [
{
"name": "Bob",
"email": "[email protected]",
"rel": "owner",
"links": [
{
"rel": "self",
"href": "..."
},
{
"rel": "avatar",
"href": "...",
"type": "image/jpeg"
},
{
"rel": "alternate",
"href": "...",
"type": "text/html"
}
]
},
{
"name": "Jonny",
"email": "[email protected]",
"rel": "assignee",
"links": [
{
"rel": "self",
"href": "..."
},
{
"rel": "avatar",
"href": "...",
"type": "image/jpeg"
},
{
"rel": "alternate",
"href": "...",
"type": "text/html"
}
]
}
],
"links": [
{
"rel": "self",
"href": "..."
},
{
"rel": "alternate",
"type": "text/html",
"href": "..."
},
{
"rel": "parent",
"href": "...",
"title": "The Workspace this take belongs to"
},
{
"rel": "edit",
"href": "..."
},
{
"rel": "replace",
"href": "..."
},
{
"rel": "update-status",
"href": "..."
},
{
"rel": "delete",
"href": "..."
},
{
"rel": "comments",
"count": 2,
"href": "..."
},
{
"rel": "attachments",
"count": 1,
"href": "..."
},
{
"rel": "custom-fields",
"count": 2,
"href": "..."
}
]
}
],
"links": [
{
"rel": "self",
"href": "..."
},
{
"rel": "parent",
"href": "..."
},
{
"rel": "create",
"href": "..."
}
]
}
Get Link Relations
| Type | Name | Description | Methods |
|---|---|---|---|
| tasks | self |
The current API URI of this Documents To-do | GET |
| tasks | parent |
The URI for the current Document | GET |
| tasks | create |
The URI for creating a new To-do against the Document | POST |
| task | self |
The URI for the To-do task | GET |
| task | alternate |
The web URI of the To-do task | GET |
| task | parent |
The URI for the workspace this To-do task is in | GET |
| task | edit |
The URI for updating a To-do task | PUT |
| task | update-status |
The URI for updating the status of a To-do task | PUT |
| task | delete |
The URI for setting the To-do task to deleted | DELETE |
| task | replace |
The URI for replacing assignees on the To-do task | PUT |
| actor | self |
The URI for the User | GET |
| actor | avatar |
The URI for the Users avatar | GET |
| actor | alternate |
The web Uri for the Users profile | GET |
| actor | delete |
The URI for deleting an assignment i.e. rel="assignee" | GET |
Get Error Responses
| Case | Response Code | Error Code |
|---|---|---|
| Document is deleted | 404 Not Found |
DocumentDeleted |
| User is not a member of the Workspace | 403 Forbidden |
WorkspaceMembershipRequired |
| Workspace is locked | 403 Forbidden |
WorkspaceLocked |
| Workspace is deleted | 404 Not Found |
WorkspaceDeleted |
Create To-do Against Document
This endpoint is used to create new To-do tasks that have the current document as an attachment.
Create Request
POST /tasks/document/123/todo HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty
{
"workspaceId": "This is the workspace ID",
"title": "A new task",
"description": "This is a task to do something",
"status": "NotStarted",
"dueDate": "2019-03-05",
"plannedStartDate": "2019-03-04",
"links": [
{
"rel": "assignee",
"href": "..."
}
]
}
| Name | Description | Required | Default |
|---|---|---|---|
workspaceId |
Workspace in which to create the task | Yes |
|
title |
Title of the new task | Yes |
|
description |
Description of the new task | No |
Empty |
status |
The starting status of the Task. Options are NotStarted,InProgress, and Complete |
No |
NotStarted |
dueDate |
Date that the task is completed by | No |
|
plannedStartDate |
Date that the task should be started | No |
null |
links |
Links to the assignees for this task | No |
Empty |
Create Response
If successful, this endpoint will return an empty response with a status code of 201 and a Location header containing the URI of the created to-do task.
HTTP/1.1 201 Created
Location: /tasks/123
Create Error Responses
| Case | Response Code | Error Code |
|---|---|---|
| Title is missing or empty | 400 Bad Request |
Invalid |
| Status is invalid | 400 Bad Request |
Invalid |
| Any date is malformed | 400 Bad Request |
Invalid |
| Document is deleted | 404 Not Found |
DocumentDeleted |
| 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 |
Delete To-do Against-Document
This endpoint is used to delete a To-do tasks that have the current document as an attachment.
Delete Request
DELETE /tasks/document/123/todo/987 HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty
Delete Response
If successful, this method will return an empty response with a No Content status code.
HTTP/1.1 204 No Content
Delete Responses
| Case | Response Code | Error Code |
|---|---|---|
| No Attachment for Document | 204 No Content |
No Content |
| No Attachment for Task | 204 No Content |
No Content |
| Task against the Document is deleted | 404 Not Found |
TaskDeleted |
| User is not a member of the Workspace | 403 Forbidden |
WorkspaceMembershipRequired |
| User is not Task Owner or Workspace Manager | 403 Forbidden |
InsufficientPermissions |