Using JQL with Jira REST APIs: Jira API GET Issue Simplified 101

When using Jira, you will want to access your projects from other systems. This will require you to integrate Jira with the system. The best approach to accomplish this is by the use of the Jira REST API.

Jira allows you to access the Jira platform from third-party systems without interacting with Jira’s interface. You can then issue various JQL commands to know more about your Jira Projects. You can also use the Jira API GET issue to know more about the issues of your projects.

This article discusses how to use JQL with Jira REST API.

Jira Overview

Jira is a project management and issue-tracking tool widely used in software development. Developed by Atlassian, Jira supports agile methodologies, enabling teams to plan, track, and release software efficiently. Its primary features include customizable workflows, task assignments, and real-time progress monitoring. Through Jira’s robust integration capabilities, users can connect it to numerous third-party tools, enhancing productivity across teams. Additionally, with the help of the Jira Query Language (JQL) and REST APIs, users can perform detailed searches, retrieve project data, and automate tasks, making Jira highly versatile for managing complex projects and optimizing team collaboration.

Part 1: Understanding Jira REST APIs

The Jira REST APIs help you to integrate Jira with third-party applications. You can also use the REST APIs to develop Add-Ons for Jira or Script Interactions with Jira. 

With the Jira REST APIs, you can interact with the Jira software remotely. The interaction is normally done using URI paths. 

To use a Jira REST API, an application has to make an HTTP request and parse the response. The REST API uses JSON format for communication, and HTTP methods such as GET, POST, PUT, and DELETE. The URIs for the Jira REST API takes the following format:

http://host:port/context/rest/api-name/api-version/resource-name

With Jira REST APIs, you can use Jira without having to interact with its User Interface (UI).

Part 2: Understanding JQL

JQL (Jira Query Language) provides the best way for Jira users to search for their Jira issues. It can be used by anyone, including developers, agile project managers, testers, and business users. 

Knowing how to search for issues in Jira can help you to save time. It can also help you to get exactly what you want. A combination of JQL with Jira REST API can help you to run JQL queries from remote systems. You can run Jira API GET issue queries to get details about the various issues you come across in your Jira projects. 

JQL uses the following data to filter issues:

• Fields
• Values
• Operators
• Functions
• Keywords

For example, to search for all unplanned issues, you can search for issues whose status field is not closed.

Part 3: How to use JQL with Jira REST APIs

In this section, you will understand how to use the Jira API GET issue query to get the details of various Jira Project Issues. The Jira REST API JQL allows you to send a query and get a subset issue.

The GET Method

The GET Method can help us to query data from Jira. For example let’s query for the issues that have been assigned to a particular user say, johnie. We will pass a single URL parameter (JQL) which has a JQL query as shown below:

curl -D- 
  -u johnie:johnie 
  -X GET 
  -H "Content-Type: application/json" 

https://johnie:8081/rest/api/2/search?jql=assignee=johnie

The above Jira API GET issue query will return the list of issues assigned to the user johnie. The output will be in JSON format.

We can also query the issues assigned to the user johnie and at the same time restrict the number of results. This requires us to supply two additional parameters to the Jira API GET issue query, that is, startAt and maxResults. These parameters specify the starting issue to be returned in the JQL results and the number of issues to be returned from the starting issue. The following query demonstrates this:

curl -D- 
  -u johnie:johnie 
  -X GET 
  -H "Content-Type: application/json" 

http://johnie:8081/rest/api/2/search?jql=assignee=johnie&startAt=2&maxResults=2  

In the above Jira API GET issue, we are starting at issue number 2 and the query should only return a maximum of 2 issues from the starting issue. The query will return only 2 issues in a JSON format. 

We may also need to order the results returned by the query. We can add an “order by” clause to the JQL query. This is shown below:

curl -D- 
  -u johnie:johnie 
  -X GET 
  -H "Content-Type: application/json" 

  http://johnie:8081/rest/api/2/search?jql=assignee=johnie+order+by+duedate

The above Jira API GET issue will order the results based on the due date parameter. It is also possible to restrict the fields of the returned results. We can add an additional field to the query, that is, fields, to list the Jira fields returned in the JQL results. The fields in the list should be separated using commas (,). The following query demonstrates this:

curl -D- 
  -u johnie:johnie 
  -X GET 
  -H "Content-Type: application/json" 

'http://johnie:8081/rest/api/2/search?jql=project=QA+order+by+duedate&fields=id,key'

The Jira API GET issue query will return the output in a JSON format and it will only show the details of two fields, that is, id and key, as they are the ones passed to the fields parameter in the query.

And that is how you can query for issues using the Jira API GET issue query.

The POST Method

You can also send queries using the POST request. This should be the case when the JQL query is too big to be specified in a URL parameter. The JQL query should be posted to the “search” resource of the REST API in JSON format. Other URL parameters (to url) should be added to your JSON-formatted JQL query. Consider the following example:

1. curl -D- 
  -u johnie:johnie 
  -X POST 
  -H "Content-Type: application/json" 
  --data '{"jql":"project = QA","startAt":0,"maxResults":2,"fields":["id","key"]}' 

 "http://johnie:8081/rest/api/2/search"

2. Request

curl -D- \
  -u admin:admin \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"jql":"project = QA","startAt":0,"maxResults":2,"fields":["id","key"]}' \
  "http://kelpie9:8081/rest/api/2/search"

 Response

{
    "maxResults": 2,
    "startAt": 0,
    "total": 18,
    "expand": "schema,names",
    "issues": [
        {
            "expand": "html",
            "id": "10393",
            "key": "QA-36",
            "self": "http://kelpie9:8081/rest/api/2/issue/QA-36",
            "transitions": "http://kelpie9:8081/rest/api/2/issue/QA-36/transitions"
        },
        {
            "expand": "html",
            "id": "10389",
            "key": "QA-35",
            "self": "http://kelpie9:8081/rest/api/2/issue/QA-35",
            "transitions": "http://kelpie9:8081/rest/api/2/issue/QA-35/transitions"
        }
    ]
}

And that is how you can query for issues using the Jira API JQL POST issue query.

JIRA REST API Example – Query issues

Let’s examine a thorough Jira REST API search example in JQL

Query of issues assigned to user ‘fred’In this example, we supply a single URL parameter (jql) which contains the JQL query.

Request

curl -D- \
  -u fred:fred \
  -X GET \
  -H "Content-Type: application/json" \
  http://kelpie9:8081/rest/api/2/search?jql=assignee=fred

Response

{
    "expand": "schema,names",
    "startAt": 0,
    "maxResults": 50,
    "total": 6,
    "issues": [
        {
            "expand": "html",
            "id": "10230",
            "self": "http://kelpie9:8081/rest/api/2/issue/BULK-62",
            "key": "BULK-62",
            "fields": {
                "summary": "testing",
                "timetracking": null,
                "issuetype": {
                    "self": "http://kelpie9:8081/rest/api/2/issuetype/5",
                    "id": "5",
                    "description": "The sub-task of the issue",
                    "iconUrl": "http://kelpie9:8081/images/icons/issue_subtask.gif",
                    "name": "Sub-task",
                    "subtask": true
                },
.
.
.
                },
                "customfield_10071": null
            },
            "transitions": "http://kelpie9:8081/rest/api/2/issue/BULK-62/transitions",
        },
        {
            "expand": "html",
            "id": "10004",
            "self": "http://kelpie9:8081/rest/api/2/issue/BULK-47",
            "key": "BULK-47",
            "fields": {
                "summary": "Cheese v1 2.0 issue",
                "timetracking": null,
                "issuetype": {
                    "self": "http://kelpie9:8081/rest/api/2/issuetype/3",
                    "id": "3",
                    "description": "A task that needs to be done.",
                    "iconUrl": "http://kelpie9:8081/images/icons/task.gif",
                    "name": "Task",
                    "subtask": false
                },
.
.
.
                  "transitions": "http://kelpie9:8081/rest/api/2/issue/BULK-47/transitions",
        }
    ]
}

Query of issues assigned to user ‘fred’ whilst restricting the number of results

In this example, we provide two more URL parameters(to jql): startAt and maxResults, which define the starting issue and the number of issues from that starting issue, respectively, that are returned in the JQL results.

Request

curl -D- \
  -u fred:fred \
  -X GET \
  -H "Content-Type: application/json" \
  http://kelpie9:8081/rest/api/2/search?jql=assignee=fred&startAt=2&maxResults=2

Response

{
    "expand": "schema,names",
    "startAt": 2,
    "maxResults": 2,
    "total": 6,
    "issues": [
        {
            "expand": "html",
            "id": "10123",
            "self": "http://kelpie9:8081/rest/api/2/issue/BULK-38",
            "key": "BULK-38",
            "fields": {
                "summary": "aaaaa",
                "timetracking": null,
                "issuetype": {
                    "self": "http://kelpie9:8081/rest/api/2/issuetype/5",
                    "id": "5",
                    "description": "The sub-task of the issue",
                    "iconUrl": "http://kelpie9:8081/images/icons/issue_subtask.gif",
                    "name": "Sub-task",
                    "subtask": true
                },
.
.
.
            },
            "transitions": "http://kelpie9:8081/rest/api/2/issue/BULK-38/transitions",
        },
        {


            "expand": "html",
            "id": "10108",
            "self": "http://kelpie9:8081/rest/api/2/issue/BULK-32",
            "key": "BULK-32",
            "fields": {
                 "summary": "subtasks are important, too",
                 "timetracking": null,
                 "issuetype": {
                     "self": "http://kelpie9:8081/rest/api/2/issuetype/5",
                     "id": "5",
                     "description": "The sub-task of the issue",
                     "iconUrl": "http://kelpie9:8081/images/icons/issue_subtask.gif",
                     "name": "Sub-task",
                     "subtask": true
                 },
.
.
.
            },
            "transitions": "http://kelpie9:8081/rest/api/2/issue/BULK-32/transitions",
        }
    ]
}

Conclusion

JQL commands can be implemented to learn more about your Jira Projects. You can also use the Jira API GET issue to learn more about your projects’ issues. This is what you’ve learned in this article:

• You’ve learned more about Jira REST APIs.
• You’ve learned more about JQL.
• You’ve learned how to use JQL with Jira REST APIs.
• You’ve learned how to implement the Jira API GET issue.

Discover how to leverage the Confluence REST API to automate and enhance your collaboration processes. Learn more at Confluence REST API.

To further increase your productivity and business know-how, combining Jira with Hevo Data can be very helpful. Hevo Data has baked in Jira support alongside access to other providers in its Data Warehousing Platform. Connect with us today to improve your data management experience and achieve more with your data.

FAQs