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