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. JSONP Support JSONP, or JSON-P, or JSON-with-padding, was introduced in 2005 as a way to leverage a <script> tag an web page to be able to request data in the JSON format across [...]
Previous Topic
