Filter And Paginate API Calls

Administrators can increase the security of external APIs for each site (subdomain) by whitelisting single IP addresses or IP address ranges. External API requests that come from an IP that isn’t on the whitelist will receive an Authorization has been denied for this request error message.

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.

Please update your scripts. The GET [Entity] JSON response will be updated in late April 2019. The new JSON response and a maximum of 100 records per page will only be returned if pageNum is used. This will allow current scripts to be used until the new JSON response becomes the default in June or July 2019.

 

*NEW* GET [Entity] JSON Response Update

Plutora API’s JSON response for GET [Entity] will receive an upgrade in late April 2019.

Current GET [Entity] JSON Response

Currently, (before late April 2019), Plutora’s JSON response for GET [Entity] does not contain page numbers, records per page, and so on.

[

    {...},

    {...},

    {...},

...

]

Late April GET [Entity] JSON Response

After late April 2019, 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.

In June or July 2019, the new JSON response will become the default, whether or not pageNum is used. All scripts will need to be updated to keep these changes in mind.

{

  "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.
By June or July 2019, 100 records per page will be a hardcoded maximum limit, and the new GET/[Entity] JSON response will contain returnCount, totalCount, pageNum, and recordsPerPage. Please update your scripts before then.  

 

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 <=

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.

 

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

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

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

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

 

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 new parameters have been added to allow pagination:

  • pageNum or page: 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 and recordsPerPage are empty, then return everything.
  • pageNum is empty, but recordsPerPage is provided, then return everything.
  • 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 second 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

Was this article helpful?

1 found this helpful.