Documentation API
Spécification OpenAPI (Swagger)
Format standard de l'industrie pour décrire les API RESTful. Les avantages incluent :
- Documentation interactive : Swagger UI pour tester les API dans le navigateur
- Génération de code : Générer automatiquement SDK client et stubs serveur
- Validation API : Valider requêtes/réponses contre le schéma
- Développement contract-first : Concevoir la spec API avant la mise en œuvre
Bonnes pratiques de documentation
Documentation complète
- Descriptions d'opérations claires expliquant ce que fait chaque endpoint
- Exemples de requête/réponse pour chaque opération
- Codes d'erreur et leurs significations
- Exigences d'authentification et d'autorisation
- Politiques de limitation de débit et quotas
- Avis de dépréciation et guides de migration
- Exemples de code en plusieurs langages
- Guide de démarrage et tutoriels
Versionnage d'API
Gérer l'évolution des API sans casser les clients existants. Stratégies courantes :
Les versions dans le temps
Trafic client par version
v1 est la seule version stable ; v2 est en préversion chez les premiers utilisateurs.
GET /v1/customers/1042
HTTP/1.1 200 OK
Content-Type: application/json
Exemple illustratif
Versionnage URI
Version dans le chemin URL : /v1/customers, /v2/customers
Avantages : Simple, explicite, facile à router
Versionnage par en-tête
Version dans en-tête personnalisé : X-API-Version: 2 ou Accept: application/vnd.company.v2+json
Avantages : URI propres, prise en charge de la négociation de contenu
Versionnage par paramètre de requête
Version dans query string : /customers?version=2
Avantages : Facile à mettre en œuvre, prise en charge d'une version par défaut
Bonnes pratiques de versionnage
- Versionner uniquement quand des changements cassants sont nécessaires
- Prendre en charge au moins N-1 versions (actuelle et précédente)
- Communiquer clairement les délais de dépréciation
- Utiliser versionnage sémantique (major.minor.patch) en interne
- Exposer uniquement la version majeure dans l'API publique