Overview

The blocking API lets you find both which items are blocking an item and what items are being blocked by a given item. Additionally, you can create new blockers via the API. Note: Before you mark an item as blocking, you must have an item assigned to you in the Someday, Backlog, or Current status.

/api/products/{product_id}/items/{item_number}/blocking.json

GET

Get all of the items that item_number is blocking. Returns a list of block objects that are comprised of the user who is blocking, the item object for item_number provided, and the item object, blocked, for the item that is blocked by the given item_number.

Arguments

This endpoint takes no arguments.

Example Response

[
    {
        "user": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "item": {
            "status": "backlog",
            "product": {
                "archived": false,
                "id": 1,
                "name": "sprint.ly"
            },
            "description": "Require people to estimate the score of an item before they can start working on it.",
            "tags": [
                "scoring",
                "backlog"
            ],
            "number": 188,
            "archived": false,
            "title": "Don't let un-scored items out of the backlog.",
            "created_by": {
                "first_name": "Joe",
                "last_name": "Stump",
                "id": 1,
                "email": "joe@joestump.net"
            },
            "score": "M",
            "assigned_to": {
                "first_name": "Joe",
                "last_name": "Stump",
                "id": 1,
                "email": "joe@joestump.net"
            },
            "type": "task"
        },
        "blocked": {
            "status": "accepted",
            "product": {
                "archived": false,
                "id": 1,
                "name": "sprint.ly"
            },
            "description": "",
            "tags": [
                "scoring",
                "backlog"
            ],
            "number": 208,
            "archived": false,
            "title": "Add the ability to reply to comments via email.",
            "created_by": {
                "first_name": "Joe",
                "last_name": "Stump",
                "id": 1,
                "email": "joe@joestump.net"
            },
            "score": "M",
            "assigned_to": {
                "first_name": "Joe",
                "last_name": "Stump",
                "id": 1,
                "email": "joe@joestump.net"
            },
            "type": "task"
        },
        "unblocked": true
    }
]

Error Codes

404 If product_id or item_number are invalid or unknown.
403 If the user making the request is not a member of the product_id.

POST

When you send a POST to this URI with the blocked argument, the requesting user is creating a new block in the system which is indicating that item_number is blocking the item number indicated by the blocked argument. This API call will kick off an email telling the assigned_to user of item_number that they are blocking the requesting user on blocked.

Arguments

blocked (integer, required): The item number of the item being blocked by item_number.

Example Response

{
    "user": {
        "first_name": "Joe",
        "last_name": "Stump",
        "id": 1,
        "email": "joe@joestump.net"
    },
    "item": {
        "status": "backlog",
        "product": {
            "archived": false,
            "id": 1,
            "name": "sprint.ly"
        },
        "description": "Require people to estimate the score of an item before they can start working on it.",
        "tags": [
            "scoring",
            "backlog"
        ],
        "number": 188,
        "archived": false,
        "title": "Don't let un-scored items out of the backlog.",
        "created_by": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "score": "M",
        "assigned_to": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "type": "task"
    },
    "blocked": {
        "status": "accepted",
        "product": {
            "archived": false,
            "id": 1,
            "name": "sprint.ly"
        },
        "description": "",
        "tags": [
            "scoring",
            "backlog"
        ],
        "number": 208,
        "archived": false,
        "title": "Add the ability to reply to comments via email.",
        "created_by": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "score": "M",
        "assigned_to": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "type": "task"
    },
    "unblocked": true
}

/api/products/{product_id}/items/{item_number}/blocking/{block_id}.json

GET

Fetch a single block object by its block_id.

Arguments

This endpoint takes no arguments.

Example Response

{
    "user": {
        "first_name": "Joe",
        "last_name": "Stump",
        "id": 1,
        "email": "joe@joestump.net"
    },
    "item": {
        "status": "backlog",
        "product": {
            "archived": false,
            "id": 1,
            "name": "sprint.ly"
        },
        "description": "Require people to estimate the score of an item before they can start working on it.",
        "tags": [
            "scoring",
            "backlog"
        ],
        "number": 188,
        "archived": false,
        "title": "Don't let un-scored items out of the backlog.",
        "created_by": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "score": "M",
        "assigned_to": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "type": "task"
    },
    "blocked": {
        "status": "accepted",
        "product": {
            "archived": false,
            "id": 1,
            "name": "sprint.ly"
        },
        "description": "",
        "tags": [
            "scoring",
            "backlog"
        ],
        "number": 208,
        "archived": false,
        "title": "Add the ability to reply to comments via email.",
        "created_by": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "score": "M",
        "assigned_to": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "type": "task"
    },
    "unblocked": true
}

Error Codes

404 if block_id invalid or unknown.

DELETE

Indicate that the block_id is no longer blocked. Only two users can delete a given block_id. The block object's user can delete the block. NOTE: This is a destructive operation that will delete the block entirely from the system. If the block object's item's assigned_to makes the request the block unblocked attribute is set to true.

Arguments

This endpoint takes no arguments.

Example Response

{
    "user": {
        "first_name": "Joe",
        "last_name": "Stump",
        "id": 1,
        "email": "joe@joestump.net"
    },
    "item": {
        "status": "backlog",
        "product": {
            "archived": false,
            "id": 1,
            "name": "sprint.ly"
        },
        "description": "Require people to estimate the score of an item before they can start working on it.",
        "tags": [
            "scoring",
            "backlog"
        ],
        "number": 188,
        "archived": false,
        "title": "Don't let un-scored items out of the backlog.",
        "created_by": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "score": "M",
        "assigned_to": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "type": "task"
    },
    "blocked": {
        "status": "accepted",
        "product": {
            "archived": false,
            "id": 1,
            "name": "sprint.ly"
        },
        "description": "",
        "tags": [
            "scoring",
            "backlog"
        ],
        "number": 208,
        "archived": false,
        "title": "Add the ability to reply to comments via email.",
        "created_by": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "score": "M",
        "assigned_to": {
            "first_name": "Joe",
            "last_name": "Stump",
            "id": 1,
            "email": "joe@joestump.net"
        },
        "type": "task"
    },
    "unblocked": true
}

Error Codes

404 if the block_id requested was not found.
403 If the requesting user is not authorized to manipulate the block.