The Jira platform has a very intuitive and easy-to-use user interface (UI). You can interact with Jira via the UI in the browser for all its features and functions. However, oftentimes, as a power user or administrator, you will find yourself needing to interact with Jira directly without using the UI.

For example, you might want to automate certain tasks with Jira, such as creating a new issue when a certain event happens in another application or bulk update users from a CSV file. Operations such as these can be very difficult and inefficient to perform via the normal UI. This is where APIs come in!

‍

What is an API?

Before we dive into Jira’s API, we first need to understand what is an API. API stands for Application Programming Interface. It is a mechanism for an application to allow you or another application to interact with it by using a set of pre-defined structures and protocols. In other words, it is how you can communicate with an application and ask it to perform certain actions and tasks. For example, when you are creating a new issue in Jira when clicking on the Create button, the browser makes an API call to Jira by sending the data you have entered to Jira.

There are many different types of APIs, and Jira provides two types of APIs:

Java API

The Java API allows you to interact with the Java Virtual Machine (JVM) that is running the Jira application. You can access all the functions and data that are available in Jira with the Java API, such as creating issues, listening to events, and even interacting with the database directly. Since the Java API requires direct access to the JVM, it is only available when working with Jira Data Center instances.

REST API

The REST API allows you to interact with Jira using the HTTP protocol (e.g., via a browser) and is available for both Jira Data Center and Cloud, with minor differences between the two. Since you do not have direct access to the Jira application in the Cloud, REST API is the only option for Jira Cloud. We will be using the REST API in this article.

What can you do with REST API?

That is a very good question! Atlassian provides a very comprehensive set of REST APIs for Jira Cloud that covers most of the common use cases, such as creating, updating, and deleting projects, issues, and comments, searching for issues using JQL queries, and much more.

In fact, most operations you can perform with Jira’s user interface in the browser can be achieved via REST API. You can find the full list of out-of-box REST APIs documented here.

There are many useful applications of REST API. Below are some common use cases:

• Allow administrators to automate tasks in Jira using scripts or automation tools.
• Allow integrations with other applications. For example, PagerDuty can create an Incident issue in Jira when an outage is reported.
• Allow data extraction for reporting tools. For example, extract issue data from Jira Cloud for a report or visualization using tools such as Power BI.

In our example, we will use the REST API to run a JQL query to search for some issues.

‍

Working with Jira REST API

Before we can start using REST API, we will first need to have a way to authenticate ourselves against Jira. Depending on the use case, there are several authentication mechanisms available:

• App scope/JWT: best used when calling REST APIs from Forge or Connect frameworks.
• OAuth 2 (3-legged): best used for integrations not based on the Forge or Connect frameworks.
• API token: best used for ad-hoc API calls.

For our use case, we will be running ad-hoc API calls. The easiest option would be to use Basic auth with an API token.

Getting an API token

We can generate an API token for your user account and use that for authentication when calling Jira’s REST API. Note that the API token is tied to the account it is created under. This means the same permissions for the user account will be applied when using the API token.

To generate an API token:

1. Log into your Atlassian Account page.
2. Click on the Create API token button.

‍

‍

3. Enter a descriptive label for your token. Make sure it explains the purpose of the token.

‍

‍

4. Click the Copy button to copy the token. Make sure to save the token in a safe location, as once you close the dialog, you will not be able to retrieve the token content again.

‍

‍

Once you have copied the API token and saved it in a safe location, we can use it to make REST API calls.

Calling REST API

There are many ways and tools you can use to call Jira’s REST API. In our example, we will be using the popular Postman tool. Postman is a very powerful and easy-to-use tool when working with REST APIs. Best of all, it is completely free. Even when you are writing scripts or code, Postman is still a great tool to easily test your API calls and troubleshoot problems.

To search Jira using JQL via REST API using Postman:

1. Open the Postman application. You can sign up for an account if you like or skip the account creation step.
2. Open a new tab with the + icon.
3. Enter the API’s URL https://your-domain.atlassian.net/rest/api/3/search. Make sure to change “your-domain” with your own Jira Cloud instance's URL.
4. Change the HTTP method from GET to POST.
5. Click on the Authorization tab and select Basic Auth.
6. Enter your Jira Cloud account’s email address for Username and the API token for Password.

‍

‍

7. Click the Headers tab and add a new Content-Type header with the value of application/json.

‍

‍

8. Click the Body tab, select the raw option, then JSON in the dropdown, and enter the JQL query in the text box as JSON, something like:

‍

‍

9. Click the Send button, and you should see the result of the API call at the bottom under Body.

‍

‍

Summary

API allows you to communicate with applications without the need for a user interface. Jira Cloud provides REST APIs for most of its functions and operations, so you can access them via scripts, code, or other tools such as Postman and curl.

In this article, we have barely scratched the surface of what you can do with Jira’s APIs, but I hope you are beginning to see the potential. In future articles, we will delve deeper and explore other types of APIs Jira provides and how you can leverage them to improve your experience using Jira.