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) |
Batching links¶
If, and only if, the resultset has been batched over several pages, the
response body will contain a top-level attribute batching
that 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 |
Full example of a batched request and response:
GET /plone/folder/@search?b_size=5&sort_on=path HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i 'http://nohost/plone/folder/@search?b_size=5&sort_on=path' -H 'Accept: application/json' --user admin:secret
http 'http://nohost/plone/folder/@search?b_size=5&sort_on=path' Accept:application/json -a admin:secret
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
}