Filter And Paginate API Calls

DUE LATE DECEMBER 2019: Now, the users of Plutora’s API can:

Once you have set up and tested API and have access to Swagger, you can make your GET API calls more targeted with filtering, and easier to manage with pagination.

For better performance, GET [entity] requests should use a paginated format. For example, GET releases?pageNum=0&recordsPerPage=100

GET [Entity] JSON Response

If pageNum is used, the GET [Entity] JSON response will show an array of records under the resultSet object and the maximum number of records returned will be 100 per page:

  • returnCount: The number of records returned in the current request.
  • totalCount: The number of records matching the applied filter.
  • pageNum: The number of the page returned in the current request – set by the user in the request parameters. corresponds to page 1.
  • recordsPerPage: The number of records to be returned per request – set by the user in the request parameters.
{

  "resultSet": [

    {...},

    {...},

    {...},

...

  ],

  "returnCount": A,

  "totalCount": B,

  "pageNum": C,

  "recordsPerPage": D

}

 

Parameter Fields

Plutora API’s main GET requests now have three new parameter fields in Swagger UI:

  • filter: Filter on the entity fields.
  • pageNum: The number of the page to be returned. 0 corresponds to page 1.
  • recordsPerPage: The number of records per page to be returned.

 

Filtering

Now users can retrieve the list of entities filtered by any or by multiple attributes of main GET requests. To use this feature in Postman or integration scripts, users will need to make sure that the values in their query string (for example, fields names and search values) are URL encoded.

 

Filter Operators and Date Formats

Syntax

Use the operators OR and AND, where AND takes precedence.

Filters are not case sensitive.

Maintained Operators

  • Equals, or =
  • NotEquals, or !=
  • Contains, or ~
  • NotContains, or !~
  • GreaterThan, or >
  • GreaterOrEqual, or >=
  • LessThan, or <
  • LessOrEquals, or <=
  • IsWithin

Maintained Date Formats

  • YYYY/MM/DD
  • YYYY-MM-DD
  • MM/DD/YYYY
  • DD-MM-YYYY

Backticks

Use backticks around field names and search values in Swagger. For example, `FieldName` contains `Search Value`.

The backtick symbol can be found at the top-left corner of your keyboard.

Parentheses

If you are using multiple expressions, wrap all the expressions in parentheses. Wrapping one expression only will generate an error.

INCORRECT: `name` like `ABC` or ( `displayColor` like `#` )
CORRECT: ( `name` like `ABC` ) or ( `displayColor` like `#` )

Sorting

Search filters can be sorted by adding:

"direction": "asc",

or

"direction": "desc",

For example, POST /releases/filter, which will return the list of Releases with the Name containing text “ABC” and the Id containing text “XYZ”, where the sorting will be applied by Name value:

{
"searchFilters": [
{
"property": "name",
"direction": "desc",
"value": "ABC",
"operator": "contains"
}
],
"ExpandoObject": {
"Left": "identifier",
"Operator": "contains",
"Right": "XYZ"
},
"recordsPerPage": 25,
"pageNum": 0
}

 

Filtering Examples

IsWithin Example

When listing values for IsWithin, do not put a space between the commas or only the first value will be returned. For example, if “value”: “Change 1,Change 2,Change 3”, in the example below was written “value”: “Change 1, Change 2, Change 3”, only Change 1 would be returned.

{
"searchFilters": [
{
"property": "name",
"direction": "ASC",
"value": "Change 1,Change 2,Change 3",
"operator": "iswithin",      
}
],
"recordsPerPage": 25,
"pageNum": 0
}

 

Other Filtering Examples

In the Request URLs below, instead of [domain], use your country’s Swagger link:

Retrieve only Releases with “ABC” in their Name

Swagger UI

“Filter” field value in Swagger UI: `Name` contains `ABC`.

Request URL

https://[domain]/releases?filter=%60Name%60%20contains%20%60ABC%60&pageNum=0&recordsPerPage=100

Filter Environments using Two or More Words

Swagger UI

Use backticks if you are searching for more than one word.

Type in the Swagger UI filter field: `Name` contains `API UAT Connect Legacy`

Request URL

https://[domain]/environments?filter=%60Name%60%20contains%20%60API%20UAT%20Connect%20Legacy%60&pageNum=0&recordsPerPage=100

Retrieve only Changes which have “Last Modified Date” starting from February 1, 2019

Swagger UI

Type in the Swagger UI filter field: `LastModifiedDate` GreaterOrEqual ‘2019-02-01’

Request URL

https://[domain]/changes?filter=%60LastModifiedDate%60%20GreaterOrEqual%20%E2%80%982019-02-01%60&pageNum=0&recordsPerPage=100

Retrieve only Users which have “firstName” equal “John” but “userName” not containing “Smith”

Swagger UI

Type in the Swagger UI Users GET filter field: `firstName` equals `John` and `userName` not contains `Smith` 

Request URL

https://[domain]/users?filter=%60firstName%60%20equals%20%60John%60%20and%20%60userName%60%20not%20contains%20%60Smith%60&pageNum=0&recordsPerPage=100

 

Pagination

Pagination makes API calls that might return hundreds or thousands of results easier to handle. Now, users can retrieve paginated response bodies for the main GET requests.

Pagination Parameters

Two parameters allow pagination:

  • pageNum: The number of the page to be returned.
  • recordsPerPage or limit: The number of records per page to be returned.

Pagination Rules

The first page number is 0 (zero). The second page number is and so on. 

If:

  • pageNum is provided, but recordsPerPage is empty, then return 100 records from the page requested (default value).
  • pageNum and recordsPerPage(<=100) are provided, then return requested page and amount of records.
  • pageNum and recordsPerPage(>100) are provided, then return requested page and 100 records per page.

 

Pagination Example

Retrieve the third page of users with 15 records per page

Swagger UI

Type in the Swagger UI pageNum and recordsPerpage fields: “pageNum” = 2, “recordsPerPage”=15

Request URL

https://[domain]/users?pageNum=2&recordsPerPage=15

Back to the top arrow

Be the first to find out about new features. Subscribe to the Release Notes email. Subscribe Now
1 found this helpful.