Pagination

API 0.x

Large data sets are returned as paginated data. When this occurs a pagination section will be returned in the result set. The first page of data will be returned in the response also.

{
    "pagination": {
        "results" : 7461,
        "page" : 1,
        "page_size" : 100,
        "pages" : 75
    },
    "customers": [
        { ... },
        { ... }
        ... and 98 other customers
    ]
}

Requesting Pages

You can request a different page by passing a different page parameter like:

https://domain_prefix.vendhq.com/api/products?page=23

Page size

It is possible to change the number of objects returned in the response. It can be done by passing the page_size parameter like:

https://domain_prefix.vendhq.com/api/products?page=23&page_size=200

NOTE: 200 is the maximum value of the page_size parameter.

API 2.0

Requesting subsequent pages is based on a resource specific cursor - an attribute called version which can be found on all collection resources. Here’s an example based on the brand resource:

{
  "id": "b1e2624f-f019-11e3-a0f5-b8ca3a64f8f4",
  "name": "Generic Brand",
  "deleted_at": null,
  "version": 791094
}

NOTE: The version attribute is simply a monotonically increasing integer. It is being incremented every time a resource is changed. This is a global parameter and it shouldn’t be assumed that subsequent versions of the same resource will be incremented by 1.

First page

By default, the value of the after parameter will be assumed as equal 0 so it’s not necessary to use it on the first page. For a request with no after parameter or after=0, the first page of products will be returned, even if a resource with version = 0 may not exist in the given collection. The body of the response will contain 2 JSON objects. The first one, data will be a collection of the requested resource type and the second one, version will contain the lowest and highest version number of resources included in the response.

{
    "data": [
        {
            id: "0800273d-7d7f-11e5-e1c0-0aaccee64985",
            ...
        },
        ...
    ]
    "version": {
        "min": 11234566790,
        "max": 173456345676
    }
}

Subsequent pages

The response to that request should include a collection of 0 to n resources. The upper limit will probably be different depending on the endpoint. The highest version number x from this collection (the max attribute above) should be used to request the next page like:

/api/2.0/products?after=x

This should be repeated until an empty collection is returned. This will mean that all items of the collection have been returned.

Sorting

Objects in returned collections will be sorted by the version number in an ascending order.