JIRA REST API – How it is done


Posted by
Abdullahi ABDULJABAR

November 16, 2015

As consultant, I usually use JIRA REST API to execute a repetitive tasks like creating issues with attachments in bulk and when I develop plugins for JIRA. Also, I’ve seen some of our clients use REST API to create a specific report or to sync JIRA issues with other systems. So let’s take brief look into JIRA REST API.

What is REST ?

REST (Representational State Transfer) is an architectural style, and an approach to communications that is often used in the development of web services.

JIRA provides a wide range of REST API resources that helps developers create communication between JIRA and other applications; for example Atlassian connect add-ons uses REST API to communicate with JIRA. 

With these resources you can create/update/edit/delete data in JIRA using standard HTTP method like GETPUTPOST and DELETE

Atlassian REST API Browser 

Atlassian REST API Browser  provides a browser for the available JIRA REST resources and some add-ons like JIRA Agile. After installing the add-on go to Systems > Advanced Section > REST API Browser and you should see as below : 

API Browser

You will have to click on “Drop access” link in information message for the search APIs bar shown below to appear. 

search bar

{ “fields”: { “project”: { “id”: “10000” }, “summary”: “Summary of the issue created using REST API…”, “description”: “Issues description”, “issuetype”: { “id”: “3” } } }

Now let’s get started. First you will need to define the action you are trying to perform, for example : create a ticket, attach a file, add a user, get the information of specific custom field etc.

For this tutorial we will try to create a ticket using REST. To get the correct API resource, you need to use either API browser of the developer toolbox add-on or Atlassian documentation : JIRA REST API documentation 

Create API

From the screenshot above when typing the word “create”, it automatically highlights the API to perform the action. On the right side you will see the brief description of the API and the parameter options and the HTTP method that should be used to perform the request successfully.

For this example, you don’t have to provide any parameters and HTTP method you should use to create the issue is POST method. Now let’s build the body of the request using JSON format to create a ticket, I’ve already configured my JIRA instance as the following : 

Project/Custom field Name

Key/ID

Test Project

TP

REST API

10100

Sample of JSON request : 

{ “fields”: { “project”: { “key”: “TP” }, “summary”: “Summary of the issue created using REST API…”, “description”: “Description of the issue”, “issuetype”: { “id”: “3” }, “assignee”: { “name”: “admin” }, “reporter”: { “name”: “admin” }, “priority”: { “id”: “1” }, “customfield_10100”: “DATA INSERTED INTO REST API CUSTOM FIELD” } }

From the above JSON request, I’ve set the JIRA Project Key,Summary,Description,Issue Type, Assignee,Reporter,Priority and custom field (name : REST API).

Request Body

Write or copy the JSON example above into the “Request Body” of the browser and change the values like the ID of the issue type, priority, custom field and Project key to you own JIRA instance values. Once it’s ready, click Send button and you should see the response message as shown below : 

response

Response message should show the Id, key and full URL to newly created ticket. You can use the URL to find the actual ticket in your project.

CF

Congratulations, you’ve successfully managed to create a ticket using JIRA REST API !

REST Clients

Alternatively, you can use browsers rest clients extensions or add-ons to execute your operations. For example Advanced Rest Client Chrome extension, this extension allows you to send custom requests from your browser to any application that supports REST. 

We will use the URL for the REST to create issue from previous example : 

http://localhost:8080/rest/api/2/issue

After installing the extension in Chrome, you should see the screenshot below : 

ARC

I’ve highlighted the different sections that we will use to create a ticket in JIRA.

Name Data

URL

http://localhost:8080/rest/api/2/issue

HTTP method

POST

Header

admin:admin

Request Body

{ “fields”: { “project”: { “key”: “TP” }, “summary”: “REST API TEST”, “description”: “Creating of a ticket using project keys and issue type names using the REST API”, “issuetype”: { “id”: “3” }, “assignee”: { “name”: “admin” }, “reporter”: { “name”: “admin” }, “priority”: { “id”: “1” }, “customfield_10100”: “DATA INSERTED INTO REST API CUSTOM FIELD” } }

The only difference between the previous example in Atlassian REST API Browser add-on and Advanced Rest Client is that the login is required in the header section as shown in the table above (username:password). As we are creating the data from outside of JIRA, you must provide a user that has create issue permission in JIRA. (note: the colon is required between username and password).

The final request should look like below : 

ChromeExRequest

After clicking on “send”, the response message will appear : 

ChromeExResponse

What’s Next ? 

You’ve just seen one of the many REST API resources provided by JIRA and other Atlassian tools. The best place to find those resources and more examples on how to use them are in the links below :