Custom Fields - Huddle/huddle-apis GitHub Wiki

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`