Guides

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 value
  • in(), not in(): Search for a value in or not in a list of values
  • like, 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 statusstatus = "ACTIVE"
whose name contains domainname like "%domain%"
whose status is either ACTIVE or DISABLEDstatus in("ACTIVE", "DISABLED")
with an ACTIVE status and whose name contains domainstatus = "ACTIVE" and name like "%domain%"
with an ACTIVE status and whose name is either my-domain or starts with domainstatus = "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