Pagination

Pagination works as described in the JSON API specification, via the page[number] and page[size] query parameters. Pagination respects sorting, grouping, and filtering. The first page is page one. If no page number is specified by the client, the first page will be returned. By default, pagination is enabled and the page size is ten. If the page size specified by the client is greater than the maximum page size as configured on the server, then the query parameter will be ignored.

To set the default page size for collections of resources, use the page_size keyword argument to the APIManager.create_api() method. To set the maximum page size that the client can request, use the max_page_size argument. Even if page_size is greater than max_page_size, at most max_page_size resources will be returned in a page. If max_page_size is set to 0, the client will be able to specify arbitrarily large page sizes. If, further, page_size is set to 0, pagination will be disabled by default, and any GET request that does not specify a page size in its query parameters will get a response with all matching results.

Attention

Disabling pagination can result in arbitrarily large responses!

For example, to set each page to include only two results:

apimanager.create_api(Person, page_size=2)

Then a GET request to /api/person?page[number]=2 would yield the response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "3",
      "type": "person",
      "attributes": {
        "name": "John"
      }
    }
    {
      "id": "4",
      "type": "person",
      "attributes": {
        "name": "Paul"
      }
    }
  ],
  "links": {
    "first": "http://example.com/api/person?page[number]=1&page[size]=2",
    "last": "http://example.com/api/person?page[number]=3&page[size]=2",
    "next": "http://example.com/api/person?page[number]=3&page[size]=2",
    "prev": "http://example.com/api/person?page[number]=1&page[size]=2",
    "self": "http://example.com/api/person"
  },
  "meta": {
    "total": 6
  }
}