Reference Guide

Querying a resource

Topics:

• Pagination

•

Retrieving data for multiple occurrences in a collection

• Retrieving data for a specified resource instance

• Specifying the attributes to return in a query response

• Filtering response data

• Sorting response data

• Including data from a related resource type in a query

Pagination

When you query a resource, the server limits the size of the returned collection by default. This collection is limited to the

number of instances up to a specified pagination limit, which defaults to 100. If the requested collection has fewer instances

than this limit, the response contains the status code 200 OK and all requested instances in its body.

When the requested collection is larger than the limit, the response status code changes to 206 (Partial Content). The

response body contains only the partial collection with a size equal to the pagination limit.

Also, a special header Content-Range is added. This header contains information about how many items were returned, their

position in the whole collection, and the total size of the collection. For example, 0-99/1000 indicates that first 100 items were

returned out of 1000.

Pagination parameters and ordering

You can control the number and position of the returned partial collection by using pagination parameters and ordering.

Pagination parameters can be passed as a URL parameters limit and offset, or in a request header Range, which specifies

indexes of the first and last items in the total collection to return. <add a link to the section about ordering>

Parameter

Type Description

offset integer

Use this parameter to specify what the

first item in the returned collection. The

default is 0.

limit integer

The maximum number of entries that the

query returns.

The default pagination limit is 100; you can enter values from 1 to 2000. If 0 or less is entered as the value of the

limit, the

response is the status code 416 Range Not Satisfiable. A response to a request with a valid limit parameter contains

results up to the specified maximum number of items. If you specify a larger value, the server changes the limit to 2000.

When you limit the number of returned instances, by default, the first instances from the collection are returned based on the

ordering. To get a partial collection starting from an index other than 0, use the URL parameter offset. Its default value is 0;

other valid values are positive integers up to the total size of the collection. Invalid offset values cause the response status code

416 Range Not Satisfiable.

Another way that you can request a specific range of items from a collection is to specify the first and last index of the

instances of the partial collection using the request header Range. For example, a request with the header Range:

"100-199" retrieves the second batch of 100 items in the collection.

24 Querying a resource