Principes de Conception d'API REST qui Résistent au Temps

Les bonnes API ont ceci d'ennuyeux : elles sont prévisibles, cohérentes et faciles à comprendre. Quand la surface d'utilisation est simple, les équipes livrent plus vite et les clients cassent moins souvent.

Voici une checklist légère à garder en tête lors de la conception de nouveaux endpoints ou de la revue d'une API existante.

Principes fondamentaux

• Utilisez des noms de ressources clairs et cohérents (pensez noms).
• Alignez le comportement sur la sémantique HTTP (lecture vs écriture).
• Retournez des formes de réponse cohérentes pour que les clients n'aient pas à deviner.
• Préférez des valeurs par défaut sensées avec des paramètres optionnels pour le filtrage/tri.

Une checklist simple

1. Choisissez des chemins de ressources stables (les noms au pluriel sont une convention courante).
2. Utilisez un petit ensemble de codes de statut de façon cohérente.
3. Documentez la pagination et ce que "suivant/précédent" signifie.
4. Soyez explicite sur les exigences d'authentification et d'autorisation.
5. Ajoutez des exemples brefs dans la documentation pour le "chemin heureux" et les erreurs courantes.

Conclusion

Si vous optimisez d'abord pour la cohérence, votre API sera plus facile à documenter, plus facile à tester, et plus facile à adopter par les autres.