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.
backspace %08 tab %09 linefeed %0A creturn %0D space %20 ! %21 " %22 # %23 $ %24 % %25 & %26 ' %27 ( %28 ) %29 * %2A + %2B , %2C - %2D . %2E / %2F : %3A ; %3B < %3C = %3D > %3E ? %3F @ %40 [ %5B \ %5C ] %5D ^ %5E _ %5F ` %60 { %7B | %7C } %7D ~ %7E ¢ %A2 £ %A3 ¥ %A5 | %A6 § %A7 « %AB ¬ %AC ¯ %AD º %B0 ± %B1 ª %B2 , %B4 µ %B5 » %BB ¼ %BC ½ %BD ¿ %BF
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:
- 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