Dès lors qu’une de vos API (versionnée) manipule une liste de résultats, il vous est nécessaire de prévoir une pagination de celle-ci. Ainsi, vos consommateurs ne risquent pas de se retrouver avec un retour de leur appel trop volumineux. De même, cela vous permet d’économiser du temps de traitement et de la bande passante : si le consommateur trouve son bonheur lors du premier appel, il n’aura pas alors besoin de faire appel aux pages suivantes.
Pagination par défaut d’une API
Votre API doit permettre d’être utilisé sans que les consommateurs n’ait dès le départ à s’occuper de la pagination. Ainsi, les éléments de pagination doivent être facultatifs. S’ils ne sont pas renseignés, ils prennent alors une valeur par défaut qui est celle de la première page.
Par exemple, on peut considérer que la première page renvoie uniquement les 50 premiers résultats. Ainsi, si j’appelle l’API sans paramètre de pagination, seuls les 50 premiers résultats me sont renvoyés. Le consommateur s’en rendra compte par le retour de paramètre de pagination dans la réponse ainsi que l’utilisation d’un code retour HTTP 206 (Partial Content). Il sait alors que d’autres éléments correspondant à sa recherche sont disponibles sur d’autres pages.
Pagination dans la requête
Dans la requête, les paramètres de pagination peuvent être envoyés à l’API de deux manières différentes :
- par les query params
- par des headers HTTP
Le passage des paramètres de pagination par les query params est aujourd’hui le plus répandu. Il est possible de le mettre en place de plusieurs facons :
- deux paramètres : le premier pour préciser le numéro de page souhaité, le second pour le nombre d’éléments par page. Par exemple : page=2&par_page=10
- un seul paramètre qui contient l’indice de début et l’indice de fin (par exemple : range=15-65).
La seconde solution est la plus souple pour les consommateurs.
Pagination dans la réponse
Dans la réponse, les éléments de paginations sont tout d’abord transmis par le code retour HTTP : 200 si tous les éléments sont présents dans le retour de l’API, 206 sinon. Ainsi, si un consommateur demande les 100 premiers résultats d’une recherche mais que notre API n’en possède que 99, le code retour sera 200. En revanche, si l’API possède plus de 100 résultats, elle en retourne bien 100 comme demandé par le consommateur mais le code retour sera 206.
La réponse doit aussi préciser dans les headers HTTP les éléments suivants :
- Header Accept-Range: ressource max. Ce header doit préciser le nombre maximal d’éléments autorisés par l’API en retour. Le consommateur ne doit donc pas dépasser ce nombre lors de ses demandes. Par exemple, dans le cas d’une API retournant une liste de commande mais pas plus de 25 par appel : Accept-Range: order 25.
- Header Content-Range: min-max/count. Ce header indique la pagination utilisée par l’API (numéro de l’élément de départ et numéro de l’élément de fin) ainsi que le nombre total d’éléments disponibles. Par exemple Content-Range: 0-24/100 indique l’API a retourné les 25 premiers éléments d’une liste de 100. Le consommateur peut alors adapté sa requête suivante sur la base de ces informations.
Lien de pagination d’une API
Dans la réponse de l’API, il est d’usage d’y intégrer des liens vers les pages précédentes, suivantes, premières et dernières. Ces éléments de pagination doivent être intégrer dans le corps de la réponse. Cela simplifie le parcours des éléments paginés par le consommateurs, notamment dans le cas où ceux-ci se retrouvent sur une IHM.
Par exemple, lors d’un appel à une API renvoyant au maximum 10 éléments par appel et avec l’appel orders?range=20-29 alors les liens suivants devraient être présent dans la réponse :
- first : orders?range=0-9
- last : orders?range=50-55 (si la recherche ne retourne pas plus de 56 éléments)
- next : orders?range=30-39
- previous : orders?range=10-19
