JIRA REST API Version 2 Tutorial
JIRA REST API Overview
JIRA's REST API is for anyone who wants to interact with JIRA in a programmatic fashion. This could be developers who want to integrate their software or other Atlassian applications with JIRA, system administrators who want to automate a JIRA feature or process, or developers who want to write gadgets or mashups for JIRA.
JIRA's REST API should be your "Remote API of Choice", when working with JIRA.
Introduction to JIRA's REST API
JIRA's REST API provides access to a number of resources that are accessible via normal URLs. JIRA's response format is JSON. Because REST is built off the same technologies as the web itself, you generally do not need complicated libraries to use it. In fact, you can start exploring JIRAs REST API simply through your web browser.
JIRA's REST API is Evolving
JIRA's REST API now covers the majority of functions related to accessing and manipulating issues as well as many administration tasks.
JIRA's REST API will continue to grow to support more functions in later releases.
JIRA REST API Implementation
This section provides some background information about JIRA's REST API:
- Its URI structure
- The significance of user authentication and associated caveats
- Details about JIRA's REST API responses and expanded properties
The format of all REST URIs in JIRA is:
JIRA's REST API is provided by a plugin that is anchored under the URI path component
/rest/. Hence, if your JIRA site is running at:
Then the anchor point for REST will be:
<api-name> part of the URI is the name of the JIRA REST API, which is simply
api. There is also an
auth API, which is documented in User Authentication.
Each version of a REST API is indicated by the
<api-version> part of the URI. Since the JIRA REST API is likely to evolve, we hope to provide as much backward compatibility as possible.
The final part of the URI is the
<resource-name>. This is the actual REST API "resource" itself that determines what response you will receive. A REST resource is analogous to an object in OO programming or a database row in a database system. JIRA's REST API resources have names like "issue", "user" or "attachment".
Different resources may expect additional path parameters, often to identify an individual resource. For instance, putting all of the above together, the URI to an issue with the key MKY-1 would look like:
JIRA's REST API is protected by the same restrictions which are provided via JIRAs standard web interface. This means that if you do not log in, you are accessing JIRA anonymously. Furthermore, if you log in and do not have permission to view something in JIRA, you will not be able to view it using the JIRA REST API either.
In most cases, the first step in using the JIRA REST API is to authenticate a user account with your JIRA site. For the purposes of this tutorial we will use HTTP BASIC Authentication, but any authentication that works against JIRA will work against the REST API. This includes:
- HTTP Cookies
- Trusted Applications
- os_username/os_password query parameters
For more information about using Basic Authentication with the JIRA REST API, refer to JIRA REST API Example - Basic Authentication. For OAuth authentication refer to JIRA REST API Example - OAuth authentication.
CAPTCHA upon login was a security feature incorporated into JIRA 4.1. This feature is 'triggered' after several consecutive failed log in attempts, after which the user is required to interpret a distorted picture of a word and type that word into a text field with each subsequent log in attempt.
Be aware that you cannot use JIRA's REST API to authenticate with a JIRA site, once JIRA's CAPTCHA upon login feature has been triggered.
When you get an error response from JIRA, you can check for the presence of an X-Seraph-LoginReason header in the response, which will contain more information. A value of AUTHENTICATION_DENIED means the application rejected the login without even checking the password, which most commonly indicates that JIRA's CAPTCHA feature has been triggered.
JIRA REST API Responses
This section demonstrates how to use some of the key features of this release of the JIRA REST API.
We are using cURL in this section to make JIRA REST API calls with user authentication (above) and each call is followed by a typical JSON response.
Simple Issue Response
In the following example, BASIC Authentication is used to retrieve an issue's content. The following call (using context path "/jira"):
Would generate this standard response:
As you can see from the example above, the very first entry is something called expand. In the JIRA REST API, some of the response information is 'hidden' within expandable properties. In order to see this information, you must explicitly expand it by including the
expand query parameter in your REST API call.
Expandable properties allow the generation of optimal REST API responses, which avoid the following problems associated with offering 'too much' or 'too little' information:
- If responses provide too little information, you may require many more HTTP GET REST API calls to collect all the information you require. Overloading a JIRA site with this volume of REST API calls could generate network latency, which in turn could severely impact JIRA's performance.
- If responses provide too much information, then the network bandwidth, memory usage and processing load of a JIRA server could be severely impacted if the server receives multiple simultaneous REST API calls. For instance, if all we want to know about an issue from a REST API call is its key, then there is no need to retrieve additional information about the issue in the response, such as a potentially extensive list of comments.
Expandable properties give you some control over the data you get back.
In the following example, an issue's content is being retrieved, along with the expanded details of its
fields property, which excludes details about comments or attachments. The following call (using context path "/jira"):
Would generate a response like this (some part of the response have been removed for brevity and clarity):
Let's take a closer look at the "reporter" field from the example above:
Lots of fields like this one will have a "self" link, which takes you to the canonical location for that resource. Sometimes there will be more information there. For instance, right now we don't know the timezone of the user. Hence, if we follow that link (using context path "/jira"):
Would generate a response like this:
This gives us the timezone of the user "admin". There is also an expand option here which shows we can also get the users groups.
Would generate a response like this:
For system fields the field_id and field_name will be the same. For custom field the field_id will be a unique descriptor in the format of customfield_10040 while the field_name will be the text description provided when it is created (e.g. "Participants").
The field_type is intended to provide some indication about the format and content of field_value. It is intended to be an opaque identifier.
The format of field_value will vary depending on the field in question. For description, for instance, it will be a simple string. For comment it will be an array of comment objects.
Within the fields section all text will be presented in its raw format. If you have configured a field to use the wiki renderer then you may also want to get the HTML rendered version of the field. This can be accessed via the renderedFields expandable entity when you provide the expand=renderedFields query parameter.
Modifying JIRA Data
Example #1: Graphing Image Links
Let's write a small python script that will use our REST interface to graph the relationships between issues in our JIRA site.
We'll use the small helper library (restkit) to simplify the REST requests. This library is not strictly necessary — after all, REST is just HTTP. However, restkit can be used for convenience. We also rely on Google Charts to do the actual graphing for us too.
Using the JIRA REST API is fairly simple:
- you make an HTTP call,
- get some data back,
- then do something with that data.
In the following example, 95% of the code is doing something other than interacting with the JIRA REST API. So before we see the full example, let's highlight the actual REST usage out of context to show how simple it usually is. This example uses Python:
This performs a GET on the issue, checks for a successful response, and the parses the JSON response into a Python dictionary. The filters=[auth] line is how we told restkit to perform BASIC Authentication. Later on, we'll reach into this Python dictionary to grab the data we want for our work:
You can view the full source by downloading the attachment: draw-chart.py
You can see the script's command line options using the standard command:
You can test this against your JIRA site with:
The output should look similar to:
Open up the issue_graph.png to show an image that should look something like this:
Example #2: Quickview Inline Dialog Plugin
This time, we'll create a JIRA plugin that uses the REST API. We want to look through all the comments on the issue and add a little tooltip that will pop up when you hover over a link to a JIRA issue.
The popup should contain a "quick view" of information about the target issue (similar to the example shown in the following image) so that we do not have to click the issue's link to see this information.
First, we define the Web Resource Context in our atlassian-plugin.xml:
Then we have
linker.js look in the comment body for URLs that 'look like' they might point to JIRA issues. Next, obtain the JSON representation of the issue using JIRA's REST API, do some quick formatting on it and put it into an AUI InlineDialog.
You can download the full demo plugin here: demo-plugin-src.zip
- The Atlassian REST API space is the central point for all Atlassian REST API documentation. providing overviews and links to product-specific APIs.
- The Atlassian REST API Design Guidelines is a general, cross-product explanation of Atlassian's overall approach to REST. You can read that later to learn more about what is guiding our overall approach in JIRA.
- JIRA REST Java Client Library is a sample implementation of JIRA REST client, which should help all Java and JVM-based languages developers take advantage of JIRA REST API easily and quickly.
JIRA REST clients
- JIRA REST Java Client Library is a sample open source implementation (Apache license) of JIRA REST client developed by Atlassian. This implementation evolves together with JIRA REST API itself, helps driving, validating and testing it. We encourage everyone willing to use JIRA REST API capabilities from a Java or any JVM-based language program to try it out and give us feedback.