Batching

Representations of collection-like resources are batched or paginated if the size of the resultset exceeds the batching size:

{
  "@id": "http://.../folder/search",
  "batching": {
    "@id": "http://.../folder/search?b_size=10&b_start=20",
    "first": "http://.../plone/folder/search?b_size=10&b_start=0",
    "last": "http://.../plone/folder/search?b_size=10&b_start=170",
    "prev": "http://.../plone/folder/search?b_size=10&b_start=10",
    "next": "http://.../plone/folder/search?b_size=10&b_start=30"
  },
  "items": [
    "..."
  ],
  "items_total": 175
}

If the entire resultset fits into a single batch page (as determined by b_size), the top-level batching links will be omitted.

Top-level attributes

Attribute	Description
@id	Canonical base URL for the resource, without any batching parameters
items	Current batch of items / members of the collection-like resource
items_total	Total number of items
batching	Batching related navigation links (see below)

Batching links

If, and only if, the result set has been batched over several pages, the response body will contain a top-level attribute batching which contains batching links. These links that can be used to navigate batches in a hypermedia fashion:

Attribute	Description
@id	Link to the current batch page
first	Link to the first batch page
prev	Link to the previous batch page (if applicable)
next	Link to the next batch page (if applicable)
last	Link to the last batch page

Parameters

Batching can be controlled with two query string parameters. In order to address a specific batch page, the b_start parameter can be used to request a specific batch page, containing b_size items starting from b_start.

Parameter	Description
b_size	Batch size (default is 25)
b_start	First item of the batch

The following is a full example of a batched request and response:

http

GET /plone/folder/@search?b_size=5&sort_on=path HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET 'http://nohost/plone/folder/@search?b_size=5&sort_on=path' -H "Accept: application/json" --user admin:secret

httpie

http 'http://nohost/plone/folder/@search?b_size=5&sort_on=path' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/folder/@search?b_size=5&sort_on=path', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@id": "http://localhost:55001/plone/folder/@search",
    "batching": {
        "@id": "http://localhost:55001/plone/folder/@search?b_size=5&sort_on=path",
        "first": "http://localhost:55001/plone/folder/@search?b_start=0&b_size=5&sort_on=path",
        "last": "http://localhost:55001/plone/folder/@search?b_start=5&b_size=5&sort_on=path",
        "next": "http://localhost:55001/plone/folder/@search?b_start=5&b_size=5&sort_on=path"
    },
    "items": [
        {
            "@id": "http://localhost:55001/plone/folder",
            "@type": "Folder",
            "description": "",
            "review_state": "private",
            "title": "Folder",
            "type_title": "Folder"
        },
        {
            "@id": "http://localhost:55001/plone/folder/doc-1",
            "@type": "Document",
            "description": "",
            "review_state": "private",
            "title": "Document 1",
            "type_title": "Page"
        },
        {
            "@id": "http://localhost:55001/plone/folder/doc-2",
            "@type": "Document",
            "description": "",
            "review_state": "private",
            "title": "Document 2",
            "type_title": "Page"
        },
        {
            "@id": "http://localhost:55001/plone/folder/doc-3",
            "@type": "Document",
            "description": "",
            "review_state": "private",
            "title": "Document 3",
            "type_title": "Page"
        },
        {
            "@id": "http://localhost:55001/plone/folder/doc-4",
            "@type": "Document",
            "description": "",
            "review_state": "private",
            "title": "Document 4",
            "type_title": "Page"
        }
    ],
    "items_total": 8
}