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.
- sortarray of stringsoptionalAn array of sort values. To sort descending, put a
-in front of the value, i.e.
- includearray of stringsoptionalAn 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.
- metaarray of stringsoptionalAn 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.
- filterobjectoptionalThe 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
- pageobjectoptionalUsed for paginating results.Show child fields
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"
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
# 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 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.
# 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 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.
# 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"
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.
$ curl -g \https://api.cycle.io/v1/containers?filter[image]=5a14ddd8b6393d0001976f32 \-H"X-Hub-Id=HUB_ID"
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.
$ 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"