Skip to content

Custom Fields

Jump to bottom
Jonny Olliff-Lee edited this page Feb 12, 2021 · 5 revisions

Custom Fields

Summary

APIs for creating, retrieving and updating Custom Fields

Operations

Operation
Retrieve Custom Field by ID
Retrieve Custom Fields for a Workspace
Create a Custom Field for a Workspace
Update a Custom Field
Retrieve Custom Fields for a Task

Retrieve Custom Field by ID

This end point returns a single Custom Field based on its ID.

GET Custom Field by ID Request

GET /tasks/workspace/123/customfields/456
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

GET Custom Field by ID Response

{
    "id": 456,
    "name": "The name of the Custom Field",
    "enabled": true,
    "values": [
        "the different",
        "options that",
        "can be used",
        "on a Task"
    ],
    "sortOrder": 1,
    "links": [
        {
            "rel": "self",
            "href": "..."
        },
        {
            "rel": "parent",
            "href": "..."
        },
        {
            "rel": "edit",
            "href": "..."
        }
    ]
}

GET Custom Field by ID Link Relations

Type Name Description Methods
links self The current API URI for Custom Field GET
links parent The URI for the Custom Fields in a Workspace GET
links edit The URI for updating this Custom Field. Only returned for Workspac Managers. PUT

GET Custom Field by ID Error Responses

Case Response Code Error Code
Custom Field is deleted 404 Not Found CustomFieldDeleted
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 Custom Fields for a Workspace

This end point returns the name, values, and enabled status of Custom Fields created in a Workspace.

GET Custom Fields for Workspace Request

GET /tasks/workspace/123/customfields
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

GET Custom Fields for Workspace Response

{
    "customFields": [
        {
            ...See Retrieve Custom Field by ID for details...
        }
    ],
    "links": [
    {
      "rel": "self",
      "href": "..."
    },
    {
      "rel": "parent",
      "href": "..."
    },
    {
      "rel": "create",
      "href": "..."
    }
  ]
}

GET Custom Fields for Workspace Link Relations

Type Name Description Methods
links self The current API URI for Custom Field in a Workspace GET
links parent The URI for the Workspace GET
links create The URI for creating a Custom Field. Only returned for Workspac Managers. POST

GET Custom Fields for Workspace Error Responses

Case Response Code Error Code
Custom Field is deleted 404 Not Found CustomFieldDeleted
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 a Custom Field for a Workspace

This endpoint creates a new Custom Field on the Workspace.

POST Create Custom Field Request

POST /tasks/workspace/123/customfields
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
    {
        "name": "Red Amber Green",
        "enabled": "true",
        "values": [
            "Stop", "Wait", "Go"
        ]
    }
}
HTTP/1.1 201 Created
Location: /tasks/workspace/123/customfields/789

{
    "id": 789,
    "name": "Red Amber Green",
    "enabled": true,
    "values": [
        "Stop", "Wait", "Go"
    ],
    "links": [
        {
        "rel": "self",
        "href": "..."
        },
        {
        "rel": "parent",
        "href": "..."
        },
        {
        "rel": "edit",
        "href": "..."
        }
    ]
}

POST Create Custom Field Link Relations

Type Name Description Methods
links self The current API URI for Custom Field GET
links parent The URI for the Custom Fields in a Workspace GET
links edit The URI for updating this Custom Field. Only returned for Workspac Managers. PUT

POST Create Custom Field Responses

Case Response Code Error Code
User is not a Manager of the Workspace 403 Forbidden WorkspaceManagerRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is deleted 404 Not Found WorkspaceDeleted

Update a Custom Field

This endpoint updates a Custom Field and it's values.

PUT Update a Custom Field Request

PUT /tasks/workspace/123/customfields/789
Content-Type: application/vnd.huddle.data+json
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty
{
    "id": 789,
    "name": "Red Amber",
    "enabled": "true",
    "values": [
        "Red", "Amber"
    ]
}

PUT Update a Custom Field Response

{
    "id": 789,
    "name": "Red Amber",
    "enabled": "true",
    "values": [
        "Red", "Amber"
    ],
    "links": [
        {
        "rel": "self",
        "href": "..."
        },
        {
        "rel": "parent",
        "href": "..."
        },
        {
        "rel": "edit",
        "href": "..."
        }
    ]
}

PUT Create Custom Field Link Relations

Type Name Description Methods
links self The current API URI for Custom Field GET
links parent The URI for the Custom Fields in a Workspace GET
links edit The URI for updating this Custom Field. Only returned for Workspac Managers. PUT

PUT Create Custom Field Responses

Case Response Code Error Code
User is not a Manager of the Workspace 403 Forbidden WorkspaceManagerRequired
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is deleted 404 Not Found WorkspaceDeleted

Retrieve Custom Fields for a Task

This endpoint returns the name and value of the Custom Fields assigned to specified Task.

GET Request

GET /tasks/123/customfields 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
{
    "customFields": [
        {
            "id": 789,
            "name": "Custom Status",
            "value": "Ready to Review",
            "links": [
                {
                    "rel": "parent",
                    "href": "..."
                }
            ]
        },
        ...other custom fields...
    ],
    "links": [
        {
            "rel": "self",
            "href": "..."
        },
        {
            "rel": "parent",
            "href": "..."
        }
    ]
}

GET Link Relations

Type Name Description Methods
customfields parent The URI for the Custom Field this entry is from GET
links self The current API URI for Custom Fields on a Task GET
links parent The URI for the Task the Custom Fields are linked to GET

GET Error Response

Case Response Code Error Code
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
Classic
Clone this wiki locally