Collections and pagination

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.

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 doesn’t 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 AUTH_TOKEN" "https://cdn.emnify.net/api/v1/endpoint?page=3&per_page=100"

Response header

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

Filtering

Filtering criteria is 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 AUTH_TOKEN" "https://cdn.emnify.net/api/v1/endpoint?q=status:0,name:arduino"

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

If filtering is applied the header contains:

• X-Filter - filter criteria

Sorting

Sorting criteria is 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 AUTH_TOKEN" "https://cdn.emnify.net/api/v1/endpoint?sort=-name,status"

If sorting is applied the header contains:

• X-Sort - sort criteria