Pagination¶

La pagination (aussi appelé Batching) désigne la spéparation des résultats en plusieurs pages (lots), pour éviter d’encombrer innutilement le serveur et de maintenir la taille de la réponse sous contrôle.

La représentation de ressources de type collection sont paginée par l’API lorsque le nombre de résultats dépasse la taille de lot (batch-size) choisie (25 par défault).

{
  "@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,
}

La taille de lot peut être contrôlée par request avec le Query-String Parameter b_size.

Des liens hypermedia pour la navigation vers les pages sont contenus dans la Top-Level Property batching lorsque les résultats ont dû être divisés en plusieurs lots.

Si au contraire tous les résultats tiennent sur une page, la Top-Level Property batching sera absente de la réponse.

Top-level Properties¶

Property	Description
`@id`	URL de base canonique pour la resource correspondante sans aucun paramètre de batching
`items`	Batch contenant les résultats de la page actuelle
`items_total`	Nombre total de résultats
`batching`	Liens hypermedia pour la navigation des batches

Batching links¶

Si les résultats sont repartis sur plusieurs pages, la Response-Body contiendra au premier niveau la propriété batching, qui contient des liens hypermedia pour la navigation des batches. Ces liens peuvent être utilisés par le client pour naviguer les pages de résultats:

Attribute	Description
`@id`	Lien vers la page actuelle
`first`	Lien vers la première page
`prev`	Lien vers la page précédente (si disponible)
`next`	Lien vers la page suivante (si disponible)
`last`	Lien vers la dernière page

Paramètres¶

La pagination peut être contrôlée à l’aide de deux paramètres (Query-String parameters). Le paramètre b_start est utilisé pour adresser une certaine page, alors que b_size détermine le nombre (maximal) de résultats par page.

Paramètre	Description
`b_size`	Nombre de résultats par page (25 par défaut)
`b_start`	Premier résultat par lequelle la page doit commencer

Exemple complet d’une réponse avec pagination:

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
}

Navigation

Related Topics