I’m the primary author of the jirametrics tool that extracts data from Jira and generates reports. This tool evolved to satisfy my own pain of not being able to get useful data out of Jira with the built-in reports and along the way, I’ve learned more about Jira internals than I ever wanted to know.
While the API’s are largely simple to use, there are many inconsistencies and places where the documentation is just wrong or the data that’s returned makes no sense. I’m going to write a couple of articles about what I’ve learned to hopefully help others who have to use the API’s.
First, there are three different flavours of Jira and they’re subtly different. Jira Server, Jira Cloud, and Jira Data Center. Cloud is hosted by Atlassian and is a basic SAAS type service. Server and Data Center are self-hosted instances that companies run in their own environments.
To make it even more confusing, I’ve seen references that Server and Data Center are actually the same binary, just deployed differently: Server on a single node and Data Center in a cluster.
As with any API, the first hard problem is authentication. If you’re writing a script to call the API from the outside (rather than a plugin that runs inside Jira), there are really only two options that you care about.
If you’re on Jira Cloud then you want to use an API-Token and if you’re on either Server or Data Center, you want to use a Personal Access Token. There are other options like OAUTH and cookie based authentication but for a simple script, those are far more work than you want.
Jira Cloud: Navigate to https://id.atlassian.com/manage-profile/security/api-tokens and create an API token there. It doesn’t matter what name you give it as this is just a reminder for you.
Then use that token like this. Example given with curl to make it easier for you to try it out.
curl -s \
--user <my_email>:<my_api_token> \
--request GET \
--header "Accept: application/json" \
--url <full_url>
For example… (obviously, not my real token)
curl -s \
--user mbowler@gargoylesoftware.com:XXXX \
--request GET \
--header "Accept: application/json" \
--url https://improvingflow.atlassian.net/rest/api/2/status
This is a good example of where I said the documentation is sometimes wrong. The docs say the API is /rest/api/2/statuses (plural) but it’s actually /rest/api/2/status (singular).
Jira Server or Jira Data Center: Log into Jira and click on your profile picture in the top right corner. Then on your profile, you’ll see a menu down the left and in there is an option to manage personal access keys. Then once you have that key, you pass it in the headers of the request as shown below.
Note that when you create the personal access token, you’ll have the option of having it auto expire after some time or staying active forever. For scripts, I usually don’t want it expiring.
curl -s \
-H "Authorization: Bearer <personal_access_token>
--request GET \
--header "Accept: application/json" \
--url <full_url>
Now that you’re able to connect and get some results, the Atlassian documentation will start to make some sense. Future articles will get into weirdness with the data returned.
Other articles about the Jira API: