Principes de conception d'API REST qui résistent à l'épreuve du temps

Les meilleures API sont ennuyeuses dans le bon sens du terme : prévisibles, cohérentes et faciles à comprendre. Quand la surface est simple, les équipes livrent plus vite et les clients cassent moins souvent.

Voici une liste de contrôle 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 aux noms communs).
• Alignez le comportement sur la sémantique HTTP (lecture vs écriture).
• Renvoyez des formats de réponse cohérents pour éviter les devinettes côté client.
• Privilégiez des valeurs par défaut sensées avec des paramètres de requête optionnels pour le filtrage/tri.

Une liste de contrôle 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 manière cohérente.
3. Documentez la pagination et ce que signifie « suivant/précédent ».
4. Soyez explicite sur les exigences d'authentification et d'autorisation.
5. Ajoutez de brefs exemples 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.