Recherche, tri et filtrage
Sélection vs inflation : l'API doit fournir un moyen d'éviter l'inflation, c'est-à-dire éviter au consommateur de récupérer des dizaines d'infos alors qu'une seule l'intéresse.
L'objectif est de contribuer aux performances des échanges et soulager les consommateurs qui devront opérer des filtres ou tris sur les données récupérées en les traitant directement dans l'API.
devraitPour des ressources de type collection comportant un nombre important d'éléments, il faut favoriser les performances du réseaux et des ressources du client en proposant ce type de paramètres optionnels :| Nom paramètre | Effet | Exemple |
|---|---|---|
| select | permet de ne sélectionner qu'une portion du JSON en appliquant un filtre sur les attributs | ?select=age:35,pays:france |
| unselect | le contraire de select, filtre le JSON en ne retenant que les items qui ne matchent pas aux critères | ?unselect=nom:dupont |
| sort | trier la collection d'objet sur le critère d'un attribut (préfixe "-" pour un ordre inversé) | ?sort=-departement |
| pick | ne conserver que les attributs spécifiés | ?pick=nom,prenom,age |
| omit | supprimer les attributs spécifiés | ?omit=adresse,tel |
Il est parfois opportun de proposer des alias pour faciliter la recherche, dans ce cas on utilise généralement la forme d'un adjectif : GET /factures/anciennes
Les fonctionnalités select et unselect peuvent être simplifiées dans le cas de ressources simples, par un simple paramètre de query string représentant le nom de l'attribut à filter.
Par exemple si je souhaite obtenir la liste de toutes les pizzas à 8€ → GET /pizzas?price=8
Le fait d'implémenter systématiquement l'ensemble de ces fonctionnalités est dans la plupart des cas de la sur-qualité (sauf dans cas d'une factorisation portée par un framework).
Ce qui doit primer est : le bon sens, des vrais use-cases, et du pragmatisme.
Pagination
optionLorsqu'une réponse est constituée d'une longue liste ou d'un nombre d'éléments indénombrables il convient de mettre en place un système de pagination pour donner la possibilité au client de naviguer partout dans la liste et présenter à son utilisateur une interface pertinente.Le principe de fonctionnement de la pagination repose sur la notion de curseur : on fait porter au client l'index courant (curseur) de la réponse obtenue qui représente un morceau dans une liste plus complète.
Pour implémenter la pagination, se réferer à la RFC 5988.
On fournit au client un en-tête (emplacement idéal pour les méta données), exemple :
Link: <https://api.laposte.fr/contacts?page=5&size=10>; rel="next", <https://api.laposte.fr/contacts?page=3&size=10>; rel="previous"
La ressource fournissant cet en-tête serait ici la page 4 de la liste des contacts.
Si l'on souhaite fournir en plus le nombre total de résultats, on utilise l'en-tête "X-Total-Count".
X-Total-Count: 150
