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
-
404Ifproduct_idoritem_numberare invalid or unknown. -
403If the user making the request is not a member of theproduct_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 byitem_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
-
404ifblock_idinvalid 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
-
404if theblock_idrequested was not found. -
403If the requesting user is not authorized to manipulate the block.