Documentation

devraitUne API existe d'abord à partir de sa documentation, il est donc essentiel de soigner la documentation d'une API.

Dans l'idéal donner une dimension "exécutable" à la documentation, et utiliser un format adapté au monde des APIs (comme OpenAPI par exemple)

• Ne pas considérer les erreurs comme des cas à part : les erreurs sont des réponses comme les autres (avec un code statut et un corps)
• Regrouper les ressource par affinité / thématique
• La documentation ne devrait dans l'idéal contenir aucune donnée confidentielle, et donc pourrait être exposée publiquement
• Les exemples illustrant la documentation devrait pouvoir être utilisés tels quels avec n'importe quel client API
• Les changement de contrat / depréciations doivent être clairement mentionnés