Batching

Representations of collection-like resources are batched / 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 resulset 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)

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

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 '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"
        },
        {
            "@id": "http://localhost:55001/plone/folder/doc-1",
            "@type": "Document",
            "description": "",
            "review_state": "private",
            "title": "Document 1"
        },
        {
            "@id": "http://localhost:55001/plone/folder/doc-2",
            "@type": "Document",
            "description": "",
            "review_state": "private",
            "title": "Document 2"
        },
        {
            "@id": "http://localhost:55001/plone/folder/doc-3",
            "@type": "Document",
            "description": "",
            "review_state": "private",
            "title": "Document 3"
        },
        {
            "@id": "http://localhost:55001/plone/folder/doc-4",
            "@type": "Document",
            "description": "",
            "review_state": "private",
            "title": "Document 4"
        }
    ],
    "items_total": 8
}