Now that Jira 5 is out, let’s talk about one of my favorite features of this new release, Jira’s new REST API. Jira has supported remote APIs for many years with SOAP, XML-RPC, and JSON-RPC. However, telling developers that you support SOAP (and only SOAP) is like saying that you like writing applications with COBOL — it’s out of style. Today’s cool kids gravitate towards REST. It’s clean, simple, and highly portable across languages and frameworks. Jira introduced its REST API in Jira 4, but was considered alpha. One very big feature it lacked was the ability create, update, and delete issues — making it a read-only API… yes, not very RESTful. However, the work that went into building that alpha version was not wasted. Jira 5’s REST API is a full featured REST API that gives you full CRUD based access to issues and its related objects. Let’s take a look at some of the cool things you get for free with this new REST API.
Expansions and Fields Filtering
Building apps using REST APIs can sometimes be challenging if the REST resources don’t match up with your apps desired functionality. For example, multiple REST resources may have to be called just to generate a single page of a web app. This is because a single resource may not be enough to generate everything that single page needs to render. Jira 5’s REST API introduces a feature called expansions that allow you to tailor your REST request to satisfy your apps requirements. In addition to expansions, you also have the ability to filter the response you get back with just the fields you want. This has a nice side-effect of limiting the network traffic and CPU cycles generated by the requesting app. Here’s a simple example of a request and response for an issue:
To keep the response small, I have limited the response to be the summary, description, and updated fields using the fields query parameter. The response contains just the data I asked for including a few bits of metadata: id, self, and issue key. Another bit of metadata is the expand key. This key describes what additional metadata can be expanded in the request. The issue resource supports the following expansions: renderedFields, names, schema, transitions, operations, editmeta, and changelog. Just to show you what this does, let’s look at the next request/response with the names and schema expansions:
The response in this request is essentially the same as the original one above, with the addition of the names object and schema object. You can take this further by using other expansions such as the transitions expansion which will give you all the available transitions for this issue. Using expansions and fields filtering makes a single resource in the API very flexible for the consuming party.
Tools and Resources
Even though REST may be easier to understand and use compared to the remote APIs that preceded it, it’s still important to have a few tools and resources available at your disposal in order to get the best value out of REST. Last Fall, we introduced a new tool that makes it dead simple to test out our REST APIs. We call this the REST API Browser. It’s bundled in the Atlassian Developer Toolbox plugin and in the Atlassian SDK. We’ve also installed a publicly accessible version on jira.atlassian.com that you can use to browse, discover, and test our REST APIs. All of the screenshots above were generated from the REST API Browser. Another useful resource is Jira 5’s Reference REST API documentation and the Jira REST documentation on developer.atlassian.com. This documentation details all of the options, parameters, request and response bodies of the API. It’s the one documentation you’ll find yourself reviewing every time you use the API. We’ve also posted a great series of Jira 5 REST tutorials on developer.atlassian.com which includes the all important section on authentication via OAuth. We’re excited to see what you guys end up building with this new API. Let us know below what you think…
UPDATE: The Jira REST API is great for updating Jira, but what about letting your other applications know what is going on in Jira? Try webhooks, now available in Jira 5.2. For example, see how you can use webhooks to send an SMS via Twilio.