In this article, we will demonstrate the basic functionality of API 2.0. The primary focus will be using GET to query an API endpoint using cURL, as this serves as a starting point for leveraging the API for more complex queries and automation tasks. In addition, because of the number of records that can be returned in a GET API call, 100 items is the maximum that can be returned in a single call. Thus when using the API, you must loop through batches of 100 to get all items.
A Note on Syntax
As every site and use case is different, the following examples will use place holders where the user must enter their own value. In all cases the "<" and ">" should be removed:
<key> - this is the field within the response we are looking for, for example, "title" in epics or "name" in cities would be a key. For more information on available keys, please review the schema definitions at the very end of the Swagger documentation (<yoursite>.jiraalign.com/rest/align/api/docs/index.html).
<value> - the user-defined value we are searching for. If we have a city with the name Houston, name is our key, as above, and the value of that key would be Houston.
In the use cases to follow, we will show three examples:
- A plain text and easy-to-read example of the syntax
- A plain text example with the key and value entered
- A cURL ready example complete with encoding
For clarity, the examples will only show the endpoint and filter/command rather than the entire URL. For example, where we show something like:
/Epics?$top=10
The full command would look like:
curl -X GET 'https://<sitename>.agilecraft.com/rest/align/api/2/Epics?top=10' -H "Accept: application/json" -H 'Authorization: Bearer <your_API_token>'
How to cURL
cURL is a basic command-line tool available in most operating systems by default, although it may need to be installed separately on Windows. If in doubt, please contact your system admin.
The use of cURL will also require the request URL to be encoded. Think of it as a website address you would enter in a browser--if you left spaces and apostrophes in the address, the browser would not be able to interpret the address and, depending on the browser, tell you the page was not found or send you to a Google search result.
What this means for us is a request to get epics where the title is 'API' would look like this:
/Epics?$filter=title%20eq%20%27API%20Epic%27
A full list of characters and what they need to be encoded to can be found here, but these are the most commonly used:
|
Character |
Encode to |
|---|---|
|
space |
%20 |
|
" |
%22 |
|
& |
%26 |
|
' |
%27 |
|
( |
%28 |
|
) |
%29 |
|
- |
%2D |
|
. |
%2E |
Apostrophes and Quotation Marks
If you are using cURL and the command returns nothing or complains of a malformed JSON string (or any strange-looking errors) even though the command and API token looks correct, check your apostrophes (') and quotation marks (“). In most cases, the key and value for the filter will need to be enclosed in apostrophes, which then need to be encoded (%27). For long URLs, this can get a little confusing; if you are hitting an error, break it down into parts and make sure everything is where it should be and the encoding is correct.
The Authorization header should be enclosed in apostrophes (') to prevent the terminal interpretation of certain characters within the token itself.
Basic Filtering Examples
For these examples, we will use epics, but the same theory can be applied to any endpoint of the API. Not all endpoints use the same key/value pairing, so please refer to the schema definitions.
Equal to (eq)
Return all epics where the title is 'API Epic'
Syntax
/Epics?$filter=<key> eq '<value>'
Plain example
/Epics?$filter=title eq 'API Epic'
cURL encoded example
/Epics?$filter=title%20eq%20%27API%20Epic%27
Not equal (ne)
Return all epics where the title is not equal to 'API Epic'
Syntax
/Epics?$filter=<key> ne '<value>'
Plain example
/Epics?$filter=title ne 'API Epic'
cURL encoded example
/Epics?$filter=title%20ne%20%27API%20Epic%27
Greater than (gt)
Return all epics where the ID is greater than 2193
NOTE: Integers do not require apostrophe (') enclosure
Syntax
/Epics?$filter=<key> gt <value>
Plain example
/Epics?$filter=id gt 2193
cURL encoded example
/Epics?$filter=id%20gt%202193
Less than (lt)
Return all epics where the ID is less than 10
Syntax
/Epics?$filter=<key> lt <value>
Plain example
/Epics?$filter=id lt 10
cURL encoded example
/Epics?$filter=id%20lt%2010
Greater than, equal to (ge)
Return all epics where the ID is greater than or equal to 2193
Syntax
/Epics?$filter=<key> ge <value>
Plain example
/Epics?$filter=id ge 2193
cURL encoded example
/Epics?$filter=id%20ge%202193
Less than, equal to (le)
Return all epics where the ID is less than or equal to 2193
Syntax
/Epics?$filter=<key> le <value>
Plain example
/Epics?$filter=id le 2193
cURL encoded example
/Epics?$filter=id%20le%202193
Contains
Return all epics where the title contains API
Syntax
/Epics?$filter=contains(<key>,'<value>')
Plain example
/Epics?$filter=contains(title,'API')
cURL encoded example
/Epics?$filter=contains(title,%27API%27)
Starts With
Return all epics where the title starts with AP
Syntax
/Epics?$filter=startswith(<key>,'<value>')
Plain example
/Epics?$filter=startswith(title,'AP')
cURL encoded example
Epics?$filter=startswith(title,%27AP%27)
Basic Pagination
The top and skip commands can be chained together to offer proper pagination (covered later in this article). Default order by is on ID, so the first 10 epics would mean IDs 1 - 10.
Top
Return the first 10 Epics
Syntax
/Epics?$top=<value>
cURL example
/Epics?$top=10
Skip
Skip the first 521 epics and return all after
Syntax
/Epics?$skip=<value>
cURL example
/Epics?$skip=521
Selecting Fields to Display
Select
Return all epics but only display their title and ID
Syntax
Epics?$select=<key_1>,<key_2>
cURL example
Epics?$select=title,id
Filtering by Date
"createDate" : "2020-05-11T05:03:25Z"
NOTE: Trying to eq to match the time will not work here. You can only gt, lt, ge & le on the date itself. Additionally, you do not need to encode the hyphens and colons in the Date/Time field.
For example, return all epics created on or after May 11 2020
/Epics?$filter=createDate ge 2020-05-11T06:48:00Z
/Epics?$filter=createDate%20ge%202020-05-11T06:48:00Z
Will return the same results as
/Epics?$filter=createDate%20ge%202020-05-11T00:00:00Z
Filter Chaining
By chaining, we mean stringing filters together to get more useful results. To do so, take the above basic filters and place them either side of an ampersand (&).
Get all items with an ID greater than X, ordered by descending Y
Syntax
/Epics?$filter=<key> gt '<value>' & $orderby=<key> desc
Plain example
/Epics?$filter=id gt 2193 &$orderby=id desc
cURL encoded example
/Epics?$filter=id%20gt%202193&$orderby=id%20desc
Get the first 10 epics with the word ‘API’ in the title and display only the epic title, description, and owner
Syntax
/Epics?$filter=contains(<key_1>,'<value_1>') &$top=<value_2> &$select=<key_2>,<key_3>,<key_4>
Where:
key_1 = the field we are searching for
value_1 = the thing we are searching key_1 for
value_2 = the amount of results to display
<key_[2|3|4]> = the fields we want to return
Plain example
/Epics?$filter=contains(title,'API')&$top=10&$select=title,description,owner
cURL encoded example
/Epics?$filter=contains(title,%27API%27)&$top=10&$select=title,description,owner
Using And/Or
Return Cities named Houston or London
Syntax
/Citites?$filter=name eq '<value_1>' or name eq '<value_2>'
Plain example
/Cities?$filter=name eq 'Houston' or name eq 'London'
cURL encoded example
/Cities?$filter=name%20eq%20%27Houston%27%20or%20name%20eq%20%27London%27
Adding a Filter to an And/Or Request
Take out chaining with ampersands and add it onto our and/or statement:
Return all cities where the name contains ‘ton’ but is not Houston and display only the name
Syntax
/Cities?$filter=contains(<key>,'value_1>') and <key> ne '<value>' &$select=<key>
Plain example
/Cities?$filter=contains(name,'ton') and name ne 'Houston' &$select=name
cURL encoded example
/Cities?$filter=contains(name,%27ton%27)%20and%20name%20ne%20%27Houston%27&$select=name
Print 
PDF
Join the Atlassian Community!
The Atlassian Community is a unique, highly collaborative space where customers and Atlassians come together. Ask questions and get answers, start discussions, and collaborate with thousands of other Jira Align customers. Visit the Jira Align Community Collection today.
Need to contact Jira Align Support? Please open a support request.