Pager

We support paging for all collections--nested collections within parent resources or otherwise. All collections will be pageable and thus have a pager and data object.

There is a wide range of methods clients may choose to implement paging. We want to support as many as we can, but a focus is paid to simplicity and the ability to navigate embedded, or nested, collections of a resource. Some features a client could offer using Shield's pagination framework:

Usage

Collections will be wrapped into Pageable objects. The collection's elements are contained in data property and the pager property holds the instance of a Pager to use to navigate the collection.

The default records returned per call is 10, and the maximum number that can be returned is 100. The limit and offset parameters allow navigation through larger data sets. Responses include a total field, which specifies the total number of records available via pagination. For performance reasons, the offset parameter is limited to a maximum value of 10000.

To further illustrate, this is how a list of drives in a game will be returned. The pageable in this snippet is drives and has returned the first result.

{
    "id": "2e550c17-631b-4536-bdb3-e974449c21f9",
    "season": 2015,
    "drives": {
        "pager": {
            "previous": null,
            "self": "https://<domain>/games/2e550c17-631b-4536-bdb3-e974449c21f9/drives?s={"$take":10, "$skip":0, "$sort": {"firstDowns":-1,"yards":1}}",
            "next": "https://<domain>/games/2e550c17-631b-4536-bdb3-e974449c21f9/drives?s={"$take":10, "$skip":10, "$sort": {"firstDowns":-1,"yards":1}}",
            "limit": 10,
            "offset": 0,
            "total" : 347,
            "sort" : {"firstDowns":-1,"yards":1}
        },
        "data": [
            {
                "the actual paged results..."
            }
        ]
    }
}

Fields

Name Default Field Default Value Type Description
previous * URL The fully qualified URL to the previous page in the collection; null if this is the first
next * URL The fully qualified URL to the next page in the collection; null if this is the last
self * URL The fully qualified URL to the this page in the collection
offset * 0 Integer The current position of an element relative to the resource
limit * 10 Integer number of items to be returned. a.k.a the page size.
sort * Map Direction and list of properties used to sort collection.
total * Integer Total count of elements

Examples