Pagination

Allows balancing of retrieved items compared to speed/size.

• By default, each page contains 100 items maximum. You need to iterate through pages linked to get the other items
• You can change the page max the URI with the limit keyword, and iterate with the header standard link

Example

GET /v1/jobs?limit=2

curl 'http://localhost:12340/v1/jobs?limit=2'

(To have the first 2 items)

Then,

GET /v1/jobs?limit=2&page=2

curl 'http://localhost:12340/v1/jobs?limit=2&page=2'

To get the second page.

Count-only requests

If you only need the number of matching resources, use HEAD on list endpoints:

• HEAD /services
• HEAD /devices
• HEAD /devices/{device}/presets
• HEAD /jobs

This is useful when you only need the caldera-total-results header.
 

Sorting

Allows you to get the desired order to process resources faster or smarter.

• Default sorting is based on the default sorting of each service and their speed to answer
• Multiple Sort options can not be combined
• Note that the :asc or :desc suffixes are mandatory

Syntax

sort=<field1>:(asc|desc)[,<field2>:(asc|desc)...]

Example

Example to get the jobs sorted using finished timestamps and the header information:

GET /v1/jobs?sort=form.evolution.finished:desc

curl 'http://localhost:12340/v1/jobs?sort=form.evolution.finished:desc'

Filtering

Gets only the relevant data to speed up the communication.

• Filters can be combined with & or |, and * (Wildcards)
• Sub-nodes can be used for example: form.message, but not in arrays.

Examples

curl 'http://localhost:12340/v1/devices?state=running'
curl 'http://localhost:12340/v1/devices?name=*Caldera*&state=running|stopping'
curl 'http://localhost:12340/v1/jobs?name=*ShowRoom*|*Reception*'