Pourquoi le design de requete compte
Les gros volumes sont inevitables. Sans pagination et filtrage, les clients tentent de tout recuperer et l'API devient lente.
Des regles claires protegent le backend et rendent l'integration plus simple.
Pagination offset : simple mais fragile
L'offset (`page` + `limit`) est facile a comprendre et a implementer. C'est un bon choix pour les petites collections.
Mais si les donnees changent, les pages se deplacent et peuvent creer des doublons.
Pagination cursor : stable et scalable
La pagination cursor utilise un pointeur vers le dernier element vu. Elle reste stable meme si les donnees changent.
Elle est plus complexe, mais recommandee pour les gros volumes.
Le tri doit etre explicite
Exposez un parametre `sort` et documentez les champs. Exemple : `sort=created_at` ou `sort=-created_at`.
Le tri doit etre deterministe, sinon la pagination devient incoherente.
Regles de filtrage
Utilisez les query params : `/orders?status=paid&customer_id=123`. C'est flexible et evolutif.
Evitez d'encoder les filtres dans le chemin sauf pour une ressource distincte.
Selection de champs
Un parametre `fields` permet de reduire la taille des reponses. C'est utile pour les clients mobiles.
Gardez une liste de champs autorises pour eviter l'exposition de donnees sensibles.
Metadonnees et totaux
Les totaux peuvent etre couteux. Retournez-les seulement si necessaire.
Pour la pagination cursor, `next_cursor` et `has_next` suffisent souvent.
Gestion des erreurs
Un filtre invalide doit renvoyer un 400 avec un message clair. Cela evite les erreurs silencieuses.
La requete fait partie du contrat : documentez-la et gardez-la stable.