Concevoir une interface avec laquelle on peut vivre
La cohérence avant la beauté
La même convention de nommage sur chaque route, la même structure de réponse, le même format de date, la même structure d'erreur. Dix routes cohérentes valent mieux que cinq brillantes et cinq différentes.
Renvoyez une structure stable : un objet enveloppeur avec des données et des métadonnées, afin de pouvoir ajouter des champs sans casser.
Des décisions qui vous reviennent
Pagination. Décidez à l'avance — par position ou par curseur — et prenez-la en charge dans chaque liste. Les listes sans pagination dépassent toujours les attentes.
Filtrage et tri. Définis et documentés, pas un champ libre où chaque consommateur invente des règles.
Identifiants. Stables, non séquentiels, et ne révélant pas d'information commerciale par leur nombre.
Les erreurs font partie du contrat
Un bon code de statut, un identifiant d'erreur fixe sur lequel on peut brancher de la logique, un message lisible et un identifiant de requête pour enquêter. Une interface qui renvoie du texte libre différent à chaque erreur oblige le consommateur à vérifier des chaînes.
Pour aller plus loin
Documentez l'interface depuis le code lui-même pour que la documentation ne vieillisse pas, et fournissez un environnement de test avec des données fictives. Et avant de publier : faites implémenter un scénario complet par quelqu'un qui n'a pas écrit l'interface — chaque question qu'il pose est un défaut de conception, pas une lacune dans sa compréhension.