Paginierung

Paginierung (auch Batching gennannt) bezeichnet das Aufteilen von Resultaten auf mehrere “Seiten”, um den Server nicht unnötig zu belasten und die Grösse von Responses kontrollierbar zu halten.

Repräsentationen von Collection-artigen Resourcen werden in der API paginiert wenn die Anzahl Resultate die Batch-Grösse (standardmässig 25) überschreitet.

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

Die Batch-Grösse kann pro Request über den Query-String Parameter b_size gesteuert werden.

Wenn Resultate über mehrere Seiten verteilt werden mussten, sind im Top-Level Property batching Hypermedia-Links zur Navigation der Batches enthalten.

Falls hingegen alle Resultate auf einer Seite Platz haben, wird das Top-Level Property batching weggelassen.

Top-level Properties

Property Description
@id Kanonische basis-URL für die entsprechende Resource, ohne irgendwelche Batching-Parameter
items Batch mit den Resultaten der aktuellen Seite
items_total Anzahl Resultate insgesamt
batching Hypermedia-Links zur Navigation der Batches

Parameter

Die Paginierung kann mittels zwei Query-String Parametern kontrolliert werden. Um eine bestimmte Seite zu addressieren, kann der Parameter b_start verwendet werden. Mit dem Parameter b_size kann gesteuert werden, wieviele Resultate eine Seite (maximal) enthalten soll.

Parameter Beschreibung
b_size Anzahl Resultate pro Seite (default ist 25)
b_start Erstes Resultat ab welchem die Batch-Seite beginnen soll

Komplettes Beispiel einer paginierten Response:

GET /dossier/@search?b_size=5&sort_on=path HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://example.org/dossier/@search",
  "batching": {
    "@id": "http://example.org/dossier/@search?b_size=5&sort_on=path",
    "first": "http://example.org/dossier/@search?b_size=5&sort_on=path&b_start=0",
    "last": "http://example.org/dossier/@search?b_size=5&sort_on=path&b_start=5",
    "next": "http://example.org/dossier/@search?b_size=5&sort_on=path&b_start=5"
  },
  "items": [
    {
      "@id": "http://example.org/plone/dossier",
      "@type": "opengever.dossier.businesscasedossier",
      "description": "",
      "title": "Folder"
    },
    {
      "@id": "http://example.org/dossier/doc-1",
      "@type": "opengever.document.document",
      "description": "",
      "title": "Document 1"
    },
    {
      "@id": "http://example.org/dossier/doc-2",
      "@type": "opengever.document.document",
      "description": "",
      "title": "Document 2"
    },
    {
      "@id": "http://example.org/dossier/doc-3",
      "@type": "opengever.document.document",
      "description": "",
      "title": "Document 3"
    },
    {
      "@id": "http://example.org/dossier/doc-4",
      "@type": "opengever.document.document",
      "description": "",
      "title": "Document 4"
    }
  ],
  "items_total": 8
}