Collections and pagination | emnify Documentation

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.

Only the collection GET requests that handle large datasets implement this feature.

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

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

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:

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 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