Filter And Paginate API Calls

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 page returned in the current request – set by the user in the request parameters. 0 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`.

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
}

Available Attributes to Filter

All the attributes listed under Get /Entity/{id} are available for filtering.

For example, in GET /Releases/{id} you can use the attributes contactName, value, lastmodifieddate, type, etc to filter the result. Ensure that you use the exact value for filtering.

				
					{
  "additionalInformation": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "type": "None",
      "dataType": "None",
      "text": "string",
      "time": "string",
      "date": "2022-07-29T06:08:45.158Z",
      "number": 0,
      "decimal": 0,
      "dateTime": "2022-07-29T06:08:45.158Z",
      "listItem": {
        "id": "00000000-0000-0000-0000-000000000000",
        "contactId": "00000000-0000-0000-0000-000000000000",
        "contactName": "string",
        "value": "string",
        "sortOrder": 0,
        "type": "None"
      },
      "multiListItem": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "contactId": "00000000-0000-0000-0000-000000000000",
          "contactName": "string",
          "value": "string",
          "sortOrder": 0,
          "type": "None"
        }
      ]
    }
  ],
  "lastModifiedDate": "2022-07-29T06:08:45.158Z",
  "id": "00000000-0000-0000-0000-000000000000",
  "identifier": "string",
  "name": "string",
  "summary": "string",
  "releaseTypeId": "00000000-0000-0000-0000-000000000000",
  "releaseType": "string",
  "location": "string",
  "releaseStatusTypeId": "00000000-0000-0000-0000-000000000000",
  "releaseStatusType": "string",
  "releaseRiskLevelId": "00000000-0000-0000-0000-000000000000",
  "releaseRiskLevel": "string",
  "implementationDate": "2022-07-29T06:08:45.158Z",
  "displayColor": "string",
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "organization": "string",
  "managerId": "00000000-0000-0000-0000-000000000000",
  "manager": "string",
  "parentReleaseId": "00000000-0000-0000-0000-000000000000",
  "parentRelease": "string",
  "plutoraReleaseType": "Enterprise",
  "releaseProjectType": "IsProject"
}

Filtering Examples

Examples of filters included in the request body:

The following endpoints in Plutora support the inclusion of filter criteria in the body of the request:
  • Post /Releases/filter
  • Post /Changes/filter
  • Post /TECRs/filter
  • Post /TEBRs/filter

Filter Releases where the name contains ‘abc’
POST /releases/filter:

				
					{
"PageNum":0,
"RecordsPerPage":25,
"ExpandoObject":{"Left":"Name","Operator":"contains","Right":"abc"}
}

Filter Releases where the name contains ‘abc xyz’ (e.g. a string value with a space)

POST /releases/filter:

				
					{
"PageNum":0,
"RecordsPerPage":25,
"ExpandoObject":{"Left":"Name","Operator":"contains","Right":"abc xyz"}
}

Filter Changes where the last Modified Date is greater than February 1, 2019
POST /changes/filter:

				
					{
"PageNum":0,
"RecordsPerPage":25,
"ExpandoObject":{"Left":"modifiedDate","Operator":"GreaterThan","Right":"2010-02-01"}
}

Filter Changes where name contains ‘abc” and type is not equal to ‘Defect’
POST /changes/filter:

				
					{
"PageNum":0,
"RecordsPerPage":25,
"ExpandoObject":{
"Left":{ "Left":"name","Operator":"contains","Right":"abc" },
"Operator":"And",
"Right":{ "Left":"type","Operator":"not equal","Right":"Defect" }
}
}

All the Get /Entities/ endpoints, for example Get /Releases/, support query string filters.

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
}

Examples of filters included on the query string

Filter Releases where the name contains ‘abc’

				
					GET /releases?filter="name contains abc"&page=0&limit=25

Filter Releases where a specific custom field contains ‘abc’

				
					GET /releases?filter="Field_Name contains abc"&page=0&limit=25

Filter Releases where the name contains ‘abc xyz’ (e.g. a string value with a space)

				
					GET /releases?filter="name contains `abc xyz`"&page=0&limit=25

Filter Changes where the last Modified Date is greater than February 1, 2019

				
					GET /changes?filter="modifiedDate `Greater Than` 2010-02-01"&page=0&limit=25
GET /changes?filter="modifiedDate greaterThan 2010-02-01"&page=0&limit=25
GET /changes?filter="modifiedDate > 2010-02-01"&page=0&limit=25

Filter Changes where name contains ‘abc” and type is not equal to ‘Defect’

				
					GET /changes?filter="name contains abc and type not equal Defect"&page=0&limit=25

Other Filtering Examples

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

  • https://usapi.plutora.com/swagger
  • https://ukapi.plutora.com/swagger
  • https://auapi.plutora.com/swagger

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

  • 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

Related Articles

Contents

Be the first to find out about new features. Subscribe to the Release Notes email.

Subscribe Now

Was this article helpful?

Thanks for your answer!

  • Updated on