Working With Collections - paging, filtering, sorting and sub-entity expansion

API supports paging, filtering, sorting on big lists ([GET] operation on collection resources). Paging, filtering and sorting are handled as query parameters in requests, while meta data describing the response are returned as header parameters.

N.B. Only the collection GET requests that handle large datasets implement this functionality.

Paging

Paging accepts query parameters that specify:

  • per_page - maximum number of resources to be retrieved within a single response (page size)
    • If per_page is < 1 the default page size is used
    • per_page is set to a predefined maximum value if it’s too big
  • page - number of returned chunk within the complete set (page#).
    • If the requested page does not exist the first (for page < 1) or the last page (for page > last_page) is returned

The response header contains:

  • Link - URLs for navigational links used to retrieve first, previous, next and last page in a dataset

  • X-Count-Per-Page - Requested per_page parameter

  • X-Current-Page - Current page number within the set

  • X-Total-Count - Total element count in the dataset

  • X-Total-Pages - Total pages count in the dataset

Example

Request

curl -v -H "Authorization: Bearer YourAuthenticationToken" "https://simforthings.bics.com/api/v1/endpoint?page=3&per_page=100"

Response header

Link:  <https://simforthings.bics.com/api/v1/endpoints?per_page=100>;rel="first", <https://simforthings.bics.com/api/v1/endpoints?page=2&per_page=100>;rel="prev", <https://simforthings.bics.com/api/v1/endpoints?page=4&per_page=100>;rel="next", <https://simforthings.bics.com/api/v1/endpoints?page=50&per_page=100>;rel="last"
X-Count-Per-Page: 100
X-Current-Page: 3
X-Total-Count: 5000
X-Total-Pages: 50

N.B. Link header should contain any (optional) filter, sort and expansion query parameters.

Filtering

Filtering criteria will be included in the request URL as q query parameter which accepts a comma-separated list of field:criteria pairs.

The following example demonstrates a GET request to /api/v1/endpoint. The q parameter then has the following query parameters:

  • status = 0
  • name = arduino

To form this request, the following pattern would be required:

/api/v1/endpoint?q=status:0,name:arduino

A valid cURL for a query of this type would look like the following:

# filter arduino endpoints with status "Enabled"
curl -v -H "Authorization: Bearer YourAuthenticationToken" "https://simforthings.bics.com/api/v1/endpoint?q=status:0,name:arduino"

When using query parameters, the following match patterns apply to queries:

entrypoint field match pattern
/api/v1/endpoint id exact match
  name wildcard
  tags wildcard
  ipAddress startsWith
  imei startsWith
  iccid exact match if size of search string is bigger than 19, else startsWith
/api/v1/sim id exact match
  imsi exact match if size of search string is bigger than 14, else startsWith
  msisdns startsWith
  iccid exact match if size of search string is bigger than 19, else startsWith
/api/v1/imsi id exact match
  digits exact match if size of search string is bigger than 14, else startsWith
/api/v1/organisation id exact match
  name wildcard
  ext_reference wildcard
  created wildcard
/api/v1/user username wildcard
  name wildcard
/api/v1/tariff_plan notes wildcard
  name wildcard
  description wildcard
/api/v1/{endpoint|sim|organisation|user}/{id}/event id exact match
OR /api/v1/event (only with new stack) tags term query
  description query string query
  severity exact match
  endpoint term query
  ip_address valid IPv4/v6 address
  imei exact match
  iccid exact match
  imsi exact match
  source exact match
  type exact match
  from date range
  until date range
  organisation term query
  alert exact match
  user term query

If filtering is applied the header contains:

  • X-Filter - filter criteria

Sorting

Sorting criteria will be included in the request URL as {sort} parameter as a comma separated list of sorting properties. The default sort order is ascending. Descending order is specified with - (dash)

# Sort endpoints by name (descending) and status
curl -v -H "Authorization: Bearer YourAuthenticationToken" "https://simforthings.bics.com/api/v1/endpoint?sort=-name,status"

If Sorting is applied the header contains:

  • X-Sort - sort criteria