Pagination, Sorting, Filtering

Pagination

Clients may request a subset of results returned by a list resource in response to a GET request. This can be done by specifying two optional query string parameters: offset – a 0-based index of first object in the list to return (defaults to 0); and limit – number of objects to return in the result (defaults to 100).

Total count

By default, each list resource returns the total number of objects it contains before pagination is applied (but after any value filters are applied). This value is returned in X-Total-Count: <number> header; this makes it possible to obtain the object count without the actual results via a HEAD request, e.g.

X-Total-Count: 3

Field selection

It is possible to select a subset of fields (object properties) to return instead of all available fields. This can be done by specifying one or more "fields" parameters in the query string. The value of this parameter is a comma-separated list of property paths to include in the response. Each property path is a dot-separated list of object property names. E.g.,

fields=id,spkey,name&fields=endpoints.id,endpoints.name

Sorting

Collection results may be explicitly sorted by one or more properties by specifying them in the "sort" query string parameter. It is a comma-separated list of property names optionally followed by :asc or :desc to specify sort direction (defaults to asc).

Query string parameter summary

Parameter Type Description
offset int 0-based index of first object in the list to return. Defaults to 0.
limit int Number of objects to return in the result. Defaults to 100.
fields string Comma-separated list of property paths to include in response. Each property path is a dot-separated list of object property names.
filter string Colon-separated name/value pair specifying the name of property whose value must contain the given value (as a substring). Results may also be filtered by nested collections' properties by specifying a dot-separated property path.
sort string Comma-separated list of properties to sort by. Only root-level properties are supported. Each property name may be optionally followed by :asc or :desc to specify sort direction (defaults to asc).
indent boolean When set to "true", responses are indented for better readability.

Docs Navigation