Qu'est-ce que Versionnage d'API
Gestion des versions d'API
Versionnage d'API
Le versionnage d'API est la pratique de gestion des modifications d'API tout en maintenant la rétrocompatibilité pour les clients existants.
Stratégies de versionnage
| Stratégie | Exemple | Description | |-----------|---------|-------------| | Chemin URL | /api/v1/users | Version dans le chemin URL | | Paramètre Query | /api/users?version=1 | Version dans le paramètre | | En-tête | X-API-Version: 1 | Version dans l'en-tête | | Content Type | Accept: application/vnd.api.v1+json | Version du type média |
Versionnage sémantique
- Majeure (v1→v2) — changements cassants
- Mineure (v1.1→v1.2) — nouvelles fonctionnalités, rétrocompatible
- Correctif (v1.1.0→v1.1.1) — corrections de bugs
Meilleures pratiques
- Documenter tous les changements (changelog)
- Supporter au moins 2 versions
- Annoncer la dépréciation à l'avance
- Utiliser les en-têtes sunset
- Fournir des outils de migration
Quand une nouvelle version est nécessaire
- Suppression de champs ou endpoints
- Modification du format de réponse
- Modification de la sémantique des paramètres
- Changement d'authentification