Filtering and sorting
The StackPath API's pagination structure can also filter and sort results based on their values. Filtering and sorting are processed server-side by StackPath. Clients should use filters and sorting to save processing time and retrieve smaller API payloads. Filters are also useful for retrieving items from StackPath without having to know their ID.
Filtering Results
Add a page_request.filter
parameter to your API call's query string containing a URL encoded filter to filter results. Filter syntax is similar to a SQL WHERE
clause.
StackPath API queries support spaces URL encoded as both the
+
character and the%20
sequence. Sample requests on this guide use the+
character for readability.
The following call requests a list of DNS zones whose domain
value is domain.com
. The filter's value is domain = "domain.com"
, URL encoded to domain+%3D+%22domain.com%22
.
$ curl --request GET \
--url 'https://gateway.stackpath.com/dns/v1/stacks/STACK_ID/zones?page_request.filter=domain+%3D+%22domain.com%22' \
--header 'accept: application/json' \
--header 'authorization: Bearer BEARER_TOKEN'
A filtered call result has the same structure as an unfiltered result. Note the response's pageInfo
section has pagination information for the filtered response and not the total result set. Large filtered result sets may be paginated.
HTTP/1.1 200 OK
Date: Tue, 07 Jul 2020 22:46:26 GMT
Content-Type: application/json
Content-Length: 475
Connection: keep-alive
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15724800; includeSubDomains
Grpc-Metadata-Content-Type: application/grpc
{
"pageInfo": {
"totalCount": "1",
"hasPreviousPage": false,
"hasNextPage": false,
"endCursor": "0"
},
"zones": [
{
"stackId": "74dd3b65-5f01-4b1e-8fcc-ad8443568af7",
"accountId": "6129025b-bbb4-4218-a912-484c990e1c55",
"id": "a6c027ed-391c-46c2-8c96-553d47cc52c7",
"domain": "domain.com",
"version": "2",
"created": "2020-07-02T21:37:52.489953Z",
"updated": "2020-07-02T21:38:28.494288Z",
"nameservers": [
"ns07ci.stackpathdns.net",
"ns00ai.stackpathdns.net"
],
"status": "ACTIVE",
"disabled": false
}
]
}
The StackPath API returns a successful response with an empty list rather than a 404 Not Found
response if the requested filter produced zero results.
Operations
Filterable properties and operations vary per StackPath API call. Not all properties can be filtered, and filterable properties have different available operations. See Error handling for more information.
StackPath supports the following operators to filter results:
=
: Perform an exact search for the filter value!=
: Filter for results that do not match the filter value<
,>
,<=
,>=
: Search for values that are less than, greater than, less than or equal, or greater than or equal to the filter valuein()
,not in()
: Search for a value in or not in a list of valueslike
,not like
: Perform a wildcard search for filter value. Use the % character as a wildcard
Complex Filters
Filters can be simple, such as a single key = "value"
match, but they can also incorporate logical and
and or
operations with parenthesis to create complex result filters. Combine these operators as needed by your application to retrieve custom data sets.
The following table describes potential filter values given an entity with name
and status
properties:
Search for items... | page_request.filter value |
---|---|
with an ACTIVE status | status = "ACTIVE" |
whose name contains domain | name like "%domain%" |
whose status is either ACTIVE or DISABLED | status in("ACTIVE", "DISABLED") |
with an ACTIVE status and whose name contains domain | status = "ACTIVE" and name like "%domain%" |
with an ACTIVE status and whose name is either my-domain or starts with domain | status = "ACTIVE" and (name = "my-domain" or name like "domain%") |
Sorting Results
The pagination structure also allows sorting the result set by a single property.
Add a page_request.sort_by
parameter to your API call's query string containing the property and direction to sort by. page_request.sort_by
's value takes the format PROPERTY[ (ASC|DESC)]
. Sort direction is optional and defaults to sort in ascending order.
For instance, add page_request.sort_by=domain+DESC
to a call's query string to order a list of DNS zones in descending order by the domain
value:
$ curl --request GET \
--url 'https://gateway.stackpath.com/dns/v1/stacks/STACK_ID/zones?page_request.sort_by=domain+DESC' \
--header 'accept: application/json' \
--header 'authorization: Bearer BEARER_TOKEN'
Note the returned DNS zones are sorted by domain name:
HTTP/1.1 200 OK
Date: Fri, 10 Jul 2020 19:06:42 GMT
Content-Type: application/json
Content-Length: 891
Connection: keep-alive
Vary: Accept-Encoding
Strict-Transport-Security: max-age=15724800; includeSubDomains
Grpc-Metadata-Content-Type: application/grpc
{
"pageInfo": {
"totalCount":" 2",
"hasPreviousPage": false,
"hasNextPage": false,
"endCursor": "1"
},
"zones": [
{
"stackId": "74dd3b65-5f01-4b1e-8fcc-ad8443568af7",
"accountId": "6129025b-bbb4-4218-a912-484c990e1c55",
"id": "a6c027ed-391c-46c2-8c96-553d47cc52c7",
"domain": "domain.com",
"version": "2",
"created": "2020-07-02T21:37:52.489953Z",
"updated": "2020-07-02T21:38:28.494288Z",
"nameservers": [
"ns07ci.stackpathdns.net",
"ns00ai.stackpathdns.net"
],
"status": "ACTIVE",
"disabled": false
}
{
"stackId": "74dd3b65-5f01-4b1e-8fcc-ad8443568af7",
"accountId": "6129025b-bbb4-4218-a912-484c990e1c55",
"id": "c3932886-434d-484d-bc65-2b2378148acc",
"domain": "domain.com,
"version": "16",
"created": "2019-10-17T04:21:25.683407Z",
"updated": "2019-10-25T18:19:13.602576Z",
"nameservers": [
"ns2lz0.stackpathdns.net",
"ns0rpn.stackpathdns.net"
],
"verified": "2019-10-17T04:30:05.187729Z",
"status": "ACTIVE",
"disabled": false
}
]
}
Error Handling
Calls with filter and sorting syntax errors return a 400 Bad Request
to the client. Syntax errors are caused by:
- Filtering on unsupported or unknown properties
- Using an unsupported filter operation
- Sorting by an unsupported or unknown property
- Using an invalid sorting direction
The result's message
property contains a list of filterable properties and their available operations.
In the following request, the client is attempting to retrieve a list of DNS zones where the unknown foo
property equals "domain.com"
by setting the page_request.filter
value foo = "domain.com"
:
$ curl -vvv --request GET \
--url 'https://gateway.stackpath.com/dns/v1/stacks/STACK_ID/zones?page_request.filter=foo+%3D+%22domain.com%22' \
--header 'accept: application/json' \
--header 'authorization: Bearer BEARER_TOKEN'
Searching on the invalid property foo
produces an error response with the call's searchable fields:
HTTP/1.1 400 Bad Request
Date: Thu, 02 Jul 2020 21:40:22 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Strict-Transport-Security: max-age=15724800; includeSubDomains
{
"code": 3,
"message": "foo is not a searchable field (domain, status, disabled)",
"details": [
{
"@type": "stackpath.rpc.RequestInfo",
"requestId": "22810ec993b92a09",
"servingData": ""
}
]
}
The StackPath API returns a similar error when the caller tries to filter a list using an invalid or unsupported operation. In the following example the client is trying to retrieve DNS zones who statuses don't match the wildcard value %domain%
using the page_request.filter
value status not like "%domain%"
:
$ curl -vvv --request GET \
--url 'https://gateway.stackpath.com/dns/v1/stacks/STACK_ID/zones?page_request.filter=status+not+like+%22%domain%25%22' \
--header 'accept: application/json' \
--header 'authorization: Bearer BEARER_TOKEN'
The not like
operator isn't supported on a DNS zone's status
property. Searching with the invalid operation produces an error response with a list of valid operations for the status
field:
HTTP/1.1 400 Bad Request
Date: Thu, 02 Jul 2020 21:43:34 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Strict-Transport-Security: max-age=15724800; includeSubDomains
{
"code": 3,
"message": "not like is not a valid operator for status (=, !=, like, in)",
"details": [
{
"@type": "stackpath.rpc.RequestInfo",
"requestId": "a42be2ecbce9a00d",
"servingData": ""
}
]
}
Updated about 1 month ago