Pagination RESTful : Maîtrisez l'art de servir vos API avec élégance

Fatigué des API Rest qui retournent des objets JSON complexes pour la pagination ? Découvrez comment exploiter les headers HTTP Range, Content-Range et Link pour une pagination plus RESTful (Votre API REST est-elle vraiment RESTful ?), plus propre et plus performante. Optimisez l'expérience de vos utilisateurs et améliorez le SEO de votre API.

Une pagination un peu plus REST

Comment paginer une liste en étant au plus près des principes REST dans notre API ?

Lorsqu'on doit retourner une liste pour un type de ressource on s'attend à retourner un tableau.

GET /api/v1/fibonacci

On obtient comme réponse :

[
  {"position":0,"value":1},
  {"position":1,"value":1},
  {"position":2,"value":2},
  {"position":3,"value":3},
  {"position":4,"value":5},
  {"position":5,"value":8},
  {"position":6,"value":13},
  {"position":7,"value":21},
  {"position":8,"value":34},
  {"position":9,"value":55},
  {"position":10,"value":89}
]

Mais si l'on désire une pagination, ce que je rencontre souvent, c'est le fait de retourner non pas un tableau mais un objet JSON qui contient le tableau et un ensemble de données sur la pagination.

GET /api/v1/fibonacci?page=0&size=10

On obtient comme réponse :

{
    "content":[
        {"position":0,"value":1},
        {"position":1,"value":1},
        {"position":2,"value":2},
        {"position":3,"value":3},
        {"position":4,"value":5}
    ],
    "totalPages":6,
    "totalElements":25,
    "numberOfElements":5,
    "size":5,
    "number":0,
    "next": "/api/v1/fibonacci?page=1&size=5",
    "last": "/api/v1/fibonacci?page=6&size=5",
    "first": "/api/v1/fibonacci?page=0&size=5"
}

Je trouve cela ni très élégant ni très RESTful ». L'appel devrait retourner une liste de ressources, pas un objet contenant la liste de ressources.

Si vous êtes de cet avis, je vais vous montrer comment faire de la pagination en utilisant la norme HTTP.

Pagination RESTful : La solution avec les headers HTTP

Nous pouvons paginer facilement en utilisant les Headers HTTP Range, Content-Range et Accept-Ranges (RFC 9110). Cette approche s'aligne davantage avec les principes REST en utilisant les headers HTTP pour la négociation de contenu et le contrôle de la ressource.

Le header `Range` : Spécifiez la portion de ressource demandée

Le Header Range permet dans la requête de spécifier la partie de la collection que nous désirons. Pour notre exemple, cela donnerait Range: fibonacci=0-9 pour les 10 premiers éléments de la suite de Fibonacci.

Exemple de requête :

GET /api/v1/fibonacci
Range: fibonacci=0-9

Le header `Content-Range` : Indiquez la portion de ressource retournée

Le Header Content-Range permet dans la réponse de spécifier la partie de la collection qui est retournée. Pour notre exemple, cela donnerait Content-Range: fibonacci=0-9/25 qui indique que l'on retourne les éléments de zéro à neuf (et donc dix éléments) sur 25 disponibles.

Exemple de réponse :

HTTP/1.1 206 Partial Content
Content-Range: fibonacci=0-9/25
Content-Type: application/json

[
  {"position":0,"value":1},
  {"position":1,"value":1},
  {"position":2,"value":2},
  {"position":3,"value":3},
  {"position":4,"value":5},
  {"position":5,"value":8},
  {"position":6,"value":13},
  {"position":7,"value":21},
  {"position":8,"value":34},
  {"position":9,"value":55}
]

Note : Le code de statut HTTP 206 Partial Content est essentiel pour indiquer que la réponse ne contient qu'une partie de la ressource demandée.

Le header `Accept-Ranges` : Signalez la prise en charge du header `Range`

Et enfin, le header Accept-Ranges qui, dans la réponse, indique que l'on accepte le header Range. Pour notre exemple, cela donnerait Accept-Ranges: fibonacci.

Exemple de réponse :

HTTP/1.1 200 OK
Accept-Ranges: fibonacci

En résumé, voici le flux complet :

Client : Envoie une requête avec le header Range pour demander une portion spécifique de la ressource.
Serveur :
- Si la plage demandée est valide, retourne une réponse avec le code de statut 206 Partial Content, le header Content-Range indiquant la portion retournée, et le header Accept-Ranges confirmant la prise en charge du header Range.
- Si la plage demandée n'est pas valide, retourne une réponse avec le code de statut 416 Range Not Satisfiable.

Navigation facilitée : L'utilisation du header `Link` pour la pagination (RFC 8288)

Nous pouvons utiliser le Header HTTP Link pour ajouter à la réponse les liens vers les autres pages.

Exemple de réponse :

HTTP/1.1 206 Partial Content
Content-Range: fibonacci=0-9/25
Accept-Ranges: fibonacci
Link: </api/fibonacci>; rel="next"; range="10-19",
      </api/fibonacci>; rel="last"; range="20-24",
      </api/fibonacci>; rel="first"; range="0-9"
Content-Type: application/json

[
  {"position":0,"value":1},
  {"position":1,"value":1},
  {"position":2,"value":2},
  {"position":3,"value":3},
  {"position":4,"value":5},
  {"position":5,"value":8},
  {"position":6,"value":13},
  {"position":7,"value":21},
  {"position":8,"value":34},
  {"position":9,"value":55}
]

Décomposition du header Link :

</api/fibonacci>; rel="next"; range="10-19" : Indique que la page suivante est accessible à l'URI /api/fibonacci et contient les éléments 10 à 19.
</api/fibonacci>; rel="last"; range="20-24" : Indique que la dernière page est accessible à l'URI /api/fibonacci et contient les éléments 20 à 24.
</api/fibonacci>; rel="first"; range="0-9" : Indique que la première page est accessible à l'URI /api/fibonacci et contient les éléments 0 à 9.

Avantages de l'utilisation du header Link :

Découvrabilité : Permet aux clients de découvrir facilement les autres pages disponibles.
Navigation simplifiée : Facilite la navigation entre les pages pour les clients.
Respect des principes REST : S'intègre parfaitement dans une architecture RESTful en utilisant les headers HTTP pour la navigation et la découverte de ressources.

Conclusion : Une API plus propre, plus RESTful et plus performante

En utilisant les headers HTTP Range, Content-Range et Link, vous pouvez implémenter une pagination RESTful plus élégante et plus performante pour vos API. Cette approche offre de nombreux avantages, notamment :

Une API plus propre et plus lisible : En évitant les objets JSON complexes pour la pagination.
Un meilleur respect des principes REST : En utilisant les headers HTTP pour la négociation de contenu et le contrôle de la ressource.
La prise en compte dans les caches : La majorité des serveurs web avec cache, reverse proxy et cache prennent en compte les headers Range et Content-Range.
Une navigation facilitée pour les clients : Grâce à l'utilisation du header Link.
Une amélioration du SEO : En fournissant des informations de pagination claires et structurées aux moteurs de recherche.

Alors, prêt à adopter la pagination RESTful ?