10X: API 2.0 GET Usage and Filters

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>.agilecraft.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:

  1. A plain text and easy-to-read example of the syntax
  2. A plain text example with the key and value entered
  3. 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?oDataFilter=contains(<key>,'<value>')

Plain example

/Epics?oDataFilter=contains(title,'API')

cURL encoded example

/Epics?oDataFilter=contains(title,%27API%27)

 

Starts With

Return all epics where the title starts with AP

Syntax

/Epics?oDataFilter=startswith(<key>,'<value>')

Plain example

/Epics?oDataFilter=startswith(title,'AP')

cURL encoded example

Epics?oDataFilter=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

The Date field takes the following format:
"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

Return all epics with an ID greater than or equal to 2193, and order the results by descending ID (default is ascending)

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?oDataFilter=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?oDataFilter=contains(title,'API')&$top=10&$select=title,description,owner

cURL encoded example

/Epics?oDataFilter=contains(title,%27API%27)&$top=10&$select=title,description,owner

 

Using And/Or 

We can also use and/or statements for boolean operations.

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?odatafilter=contains(<key>,'value_1>') and <key> ne '<value>' &$select=<key>

Plain example

/Cities?odatafilter=contains(name,'ton') and name ne 'Houston' &$select=name

cURL encoded example

/Cities?odatafilter=contains(name,%27ton%27)%20and%20name%20ne%20%27Houston%27&$select=name

 

Was this article helpful?
2 out of 2 found this helpful
Print Friendly Version of this pagePrint Get a PDF version of this webpagePDF

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.