Skip to content

paginated_objects.md

Latest commit

 

History

History
145 lines (126 loc) · 4.32 KB

paginated_objects.md

File metadata and controls

145 lines (126 loc) · 4.32 KB

Paginated Objects

Many endpoints in this API return resources that contain embedded lists of Objects. For instance, an Acquistion has a list of objects that make up the acquisition. Since there can be many objects in these lists they are presented as "Paginated object" resources.

Endpoints that return resources with paginated objects accept the following common parameters to control pagination:

Parameter Description Default Example
page Requests a specific page of the paginated set 1 ...?page=2
per_page The maximum number of items on to return on each page. Max 100 5, 20 (see below) ...?per_page=30
no_objects If set to any value, return only a count of the total number of objects associated with the containing object. This option overrides page and per_page. none ...?no_objects=1

When an object contains a paginated object resource, its (the containing object's) _links resource will have next and/or prev links pointing to the next and previous pages, if they exist.

Example Paginated Object Resource

In this example the Object resources includes in the items array are truncated for brevity.

"objects": {
    "items": [
        {...}, 
        {...}, 
        ...
    ], 
    "count": 20, 
    "total_count": 55
    "items_per_page": 20, 
    "page": 1, 
    "pages": 3, 
}

Paginated Object Fields

Field Type Req'd? Description
items array OPTIONAL An array of `Object` objects
count number OPTIONAL The number of items in the current page
total_count number REQUIRED The total number of objects associated with the containing object (e.g., the total number of objects in a given acquisition.
items_per_page number OPTIONAL The maximum number of items in one page
page number OPTIONAL The number of the current page
pages number OPTIONAL The total number of page

If the no_objects parameter is set, the paginated object resource will have only the total_count field. Otherwise all fields will be present. When the no_objects parameter is set the containing object will not have links to the next and previous pages.

Default Number of Items

Paginated object resources occur in two contexts, each with a different number of default items. If the containing object is the top-level object of the response the default number is 20. If the containing object has a parent object itself, the default number is 5.

For example the endpoint /acquisitions/6 returns on Acquisition at the top level. It contains a paginated object resource with 20 objects by default. The endpoint /acquisitions, without an ID, returns a an array of all Acquisitions. Each Acquisition in this array, since it is not the top-level object in the response, has paginated object resources with 5 items. In each case, the per_page parameter of the next and prev links will reflect this default.