Batching

Representations of collection-like resources are batched / paginated if the size of the resulset 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_size=5&sort_on=path&b_start=0", 
    "last": "http://localhost:55001/plone/folder/@search?b_size=5&sort_on=path&b_start=5", 
    "next": "http://localhost:55001/plone/folder/@search?b_size=5&sort_on=path&b_start=5"
  }, 
  "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
}