Query

When trying to gather more complete or specific data you can use query paramaters to supplement the normal return (metas, includes) and you can also add specificity to the format and the order (sort, filter). It's worth understanding that sort && filter should only be used on collections.

Query Params
  • sort
    array of strings
    optional
    An array of sort values. To sort descending, put a - in front of the value, i.e. -id.
  • include
    array of strings
    optional
    An array of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return.
  • meta
    array of strings
    optional
    An array of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled.
  • filter
    object
    optional
    The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. For example, you may want to find all containers using image X. In this case, you'd pass a filter of ?filter[image]=X
  • page
    object
    optional
    Used for paginating results.
    Show child fields
Query Example
curl "https://api.dev.cycle.io/v1/environments/5b9c2a77b6393d0001eb45fd?include=creators,stacks&meta=containers_count,instances_count,containers" \
-H
"Authorization: Bearer API_KEY"
\
-H
"X-Hub-ID=HUB_ID"

Sorting

When fetching a collection of resources, the results can be sorted based on certain criteria that will vary for each request, though most support sorting by ID. Since resource IDs encode timing, it can be a convenient way to sort by most recent, or in order of creation. Any sort value can have an - appended in front of it to turn it into a descending sort, for example -id.

Sorting Example
# Request multiple sort params with a comma
$ curl https://api.cycle.io/v1/containers?sort=-id,name \
-H
"Authorization: Bearer API_KEY"
\
-H
"X-Hub-ID=HUB_ID"

Includes

Includes are optional parameters that can be passed to add another data structure to your return - for example, including the 'creator' struct of a container that you are also fetching. The included structures are listed under the includes field of the root document.

If a field value is a resource ID, it is most likely includable.
Includes Example
# Request multiple include params with a comma
$ curl -g https://api.cycle.io/v1/containers?include=creators,stacks \
-H
"Authorization: Bearer API_KEY"
\
-H
"X-Hub-ID=HUB_ID"

Meta

Meta fields refer to optional related, but not necessarily 'expanded' information. For example, a meta field of an environment may be the number of container instances under the environment, listed by their state.

Resource objects include a meta field that will contain the requested meta data. In some cases, metas will apply to an entire collection, and will be listed under the root document's meta field. These global metas will be marked appropriately.

Meta Example
# Request multiple meta params with a comma
$ curl https://api.cycle.io/v1/containers?meta=instance_counts \
-H
"Authorization: Bearer API_KEY"
\
-H
"X-Hub-ID=HUB_ID"

Filtering

Collections of resources can be filtered based on certain criteria. You may need to find all containers using image "X", or perhaps you need to run a search on your environments for any environment with the name "Test". All this is and more is possible with filtering. Each resource request will have different filtering options available.

Filtering Example
$ curl -g \
https://api.cycle.io/v1/containers?filter[image]=5a14ddd8b6393d0001976f32 \
-H
"X-Hub-Id=HUB_ID"

Pagination

You may wish to return a subset of resource objects when fetching a collection. That's where pagination comes in. You can alter the page number, as well as the page size for each query. The maximum amount of resource objects Cycle will ever return is 100.

Pagination Example
$ curl -g https://api.cycle.io/v1/containers?page[number]=1&page[size]=20 \
-H
"Authorization: Bearer API_KEY"
\
-H
"X-Hub-ID=HUB_ID"