The issue history gives us both the name and id of any statuses that the ticket has moved through. Sometimes that’s enough but often we then need to know more about that status, such as what status category it belongs to and for that, we need to call a different API.
The two API’s
There are two different API’s that we might use for this. The first retrieves the statuses for one specific project and the other returns all statuses across the entire instance.
I used to use the project specific API and found numerous places where it just wouldn’t return some statuses that had been found in the historical data. For example, a single board can pull in issues from multiple projects and if you only ask for the statuses for one project, you’ll miss those.
So now I use the second API to get all statuses, although even that one is unreliable, as you’ll see.
- Get statuses for one project:
/rest/api/2/project/{projectIdOrKey}/statuses - Get all statuses across the Jira instance:
/rest/api/2/status
Note that the Atlassian documentation is wrong for this second API. They say it’s /rest/api/2/statuses (plural) and in fact it’s the singular /rest/api/2/status.
In theory, this API will return every status across the Jira instance. In practice, we’ve seen this to be user specific. One person can call this and get a large list of statuses and a second person can call it at the same time and get a subset of those statuses. We’ve been unable to determine what permission is in use to affect this. Bottom line is that this API is unreliable, but it’s the best we have.
Deleted statuses
An interesting point about both is that they will only return statuses that are current in the instance. So if a status has been deleted by an admin then it’s really gone, even if the historical data still references it. What this mean for practical purposes, is that if you find a status in the history that has been deleted, and you want to then find out what category it belongs to, you can’t. That information is gone. This makes looking at historical data more difficult than it should be.
If you’re trying to set up your own mapping of statuses to categories, then you might be tempted to use status names as your mapping key but this won’t work as status names are not unique across the instance. You can have multiple different statuses all called “Review” and they’re not even guaranteed to belong to the same category. The only thing that appears to be unique is the status id, and I wouldn’t be shocked if I found that wasn’t true either.
Status Categories
For the statusCategory, by definition there are only three possible values, which in an English language Jira instance will be To Do, In Progress, and Done. It shouldn’t be possible to have anything else and yet, I’ve seen at least once case where a status didn’t have a category at all. I have no idea how that would even be possible.
In Jira instances set up for other languages, the names above will be different and for this reason, you can’t rely on the category names if you’re basing your logic on the category. Fortunately, there is another field in the category that appears to be language agnostic. The key field will be one of new, for the To Do category, indeterminate for the In Progress category, and done for the Done category.
The JSON response
For a status in use by a classic project (the vast majority of projects out there), the results for a status will look like this.
{
"self": "https://improvingflow.atlassian.net/rest/api/2/status/10000",
"description": "",
"iconUrl": "https://improvingflow.atlassian.net/",
"name": "Backlog",
"untranslatedName": "Backlog",
"id": "10000",
"statusCategory": {
"self": "https://improvingflow.atlassian.net/rest/api/2/statuscategory/2",
"id": 2,
"key": "new",
"colorName": "blue-gray",
"name": "To Do"
}
}
If you have a team-managed project (formerly called NextGen) anywhere in your instance then you may find a status that looks like this. Note the extra scope section.
{
"self": "https://improvingflow.atlassian.net/rest/api/2/status/10017",
"description": "",
"iconUrl": "https://improvingflow.atlassian.net/",
"name": "Review",
"untranslatedName": "Review",
"id": "10017",
"statusCategory": {
"self": "https://improvingflow.atlassian.net/rest/api/2/statuscategory/4",
"id": 4,
"key": "indeterminate",
"colorName": "yellow",
"name": "In Progress"
},
"scope": {
"type": "PROJECT",
"project": {
"id": "10002"
}
}
}
The scope section tells you that this status is specific to one project. What makes it ugly is that we may now have two different statuses with exactly the same name, one global (without the scope) and one specifically for one project. If you’re expecting all status names to be unique, which I used to, this can come as an ugly surprise.
In the case, where there are two with the same name, the project specific one wins for that project and the global one wins in every other case.
Conclusion
As you can see, even with an API as simple as listing statuses, there is a lot that isn’t obvious.
Other articles about the Jira API:
See also the JiraMetrics tool, which is the reason I’ve had to learn the idiosyncrasies of the Jira API. If you just want access to the data then let JiraMetrics do it for you.