Les API évoluent. Nouvelles fonctionnalités, corrections, dépréciations. Mais les clients dépendent de l'interface actuelle. Le versioning permet d’évoluer sans casser les applications existantes. Ce guide présente des stratégies et des bonnes pratiques.
Pourquoi la version
Compatibilité
Les anciens clients continuent de travailler.
Évolution
Améliorer sans bloquer.
###Documentations
Clarté sur ce à quoi s'attendre.
Transition
Il est temps pour les clients de migrer.
Quand créer une version
Modifications radicales
Des changements qui rompent les contrats.
Exemples
- Supprimer le champ
- Changer le type de données
- Changer le sens
- Supprimer le point de terminaison
Ne pas créer de version pour
Des ajouts généralement compatibles.
## Stratégies de gestion des versions
URLChemin
/api/v1/utilisateurs, /api/v2/utilisateurs.
Paramètre de requête
/api/utilisateurs?version=1.
En-tête
Accept-Version: v1 ou API-Version: 2.
Négociation de contenu
Accept: application/vnd.myapi.v1+json.
Gestion des versions du chemin d'URL
Avantages
Visible, clair, facile à tracer.
Inconvénients
Les URL changent avec la version.
Exemple
OBTENIR /api/v1/produits OBTENIR /api/v2/produits
Commun
Approche la plus populaire.
Gestion des versions d'en-tête
Avantages
URL propres et sémantiquement correctes.
Inconvénients
Moins visible, plus difficile à tester.
Exemple
OBTENIR /api/produits En-tête : API-Version : 2
Versionnement sémantique
###Format
PATCH MAJEUR.MINEUR.
MAJEUR
Changements révolutionnaires.
MINEUR
Ajouts compatibles.
CORRECTIF
Des bugs sympas.
Pour les API
Généralement uniquement MAJEUR dans la version publique.
Dépréciation
Processus
Marquer comme obsolète avant de le supprimer.
###Communication
En-têtes, documentation, journal des modifications.
Chronologie
Date limite de migration.
Assistance
Combien de temps rester obsolète.
## En-têtes au coucher du soleil
En-tête HTTP
Sunset: Sat, 01 Jul 2024 00:00:00 GMT.
En-tête de dépréciation
Indique qu'il est obsolète.
###Communication
Les clients peuvent détecter automatiquement.
Migration
###Documentations
Qu'est-ce qui a changé, comment s'adapter.
### Guides
Migration étape par étape.
Assistance
Aide pendant la transition.
Chronologie
Délai raisonnable.
Compatibilité descendante
Objectif
Nouveaux clients, les anciennes API fonctionnent.
Additif
Ajoutez, ne supprimez pas.
Valeurs par défaut
Nouveaux champs avec valeurs par défaut.
###Facultatif
Nouveaux paramètres facultatifs.
Compatibilité ascendante
###Concept
Anciens clients avec de nouvelles API.
Ignorer Inconnu
Ignorez les champs inconnus.
Dégradation gracieuse
Travaillez sans nouvelles fonctionnalités.
Conception pour l'évolution
Extensibilité
Pensez aux changements futurs.
Structures génériques
Objets extensibles.
Indicateurs de fonctionnalités
N'exposez pas les fonctionnalités incomplètes.
Contrats
Définissez clairement ce que vous promettez.
Plusieurs versions
Entretien
Coût d’entretien de plusieurs.
Limites
Combien soutenir simultanément.
Politique
Établissez des règles claires.
##Documents
Par version
Documents spécifiques à la version.
Journal des modifications
Ce qui a changé entre les versions.
### Guides de migration
Comment mettre à jour.
Avis de dépréciation
Ce qui va sortir.
Outils
OpenAPI/Swagger
Spécification versionnée.
Facteur
Collections par version.
Passerelles API
Routage des versions.
Erreurs courantes
Version trop
Nouvelle version à chaque changement.
Ne pas versionner
Changement radical sans nouvelle version.
Dépréciation rapide
Ne pas laisser le temps à la migration.
Aucune communication
Des clients surpris par les changements.
## SDK et clients
Versions correspondantes
SDK v1 pour API v1.
Entretien
Gardez les SDK à jour.
###Communication
Informer des nouvelles versions.
Conclusion
La gestion des versions des API est une discipline à long terme. Choisissez une stratégie claire, communiquez les changements et prévoyez du temps pour la migration. Le résultat est des API qui évoluent sans rompre les intégrations.
##FAQ
1) Quelle stratégie de versioning utiliser ? Le chemin de l’URL est le plus courant et recommandé pour la plupart.
2) Quand augmenter la version majeure ? Pour les modifications cassantes qui ne sont pas rétrocompatibles.
3) Combien de temps pour prendre en charge l'ancienne version ? 6 à 12 mois est courant. Cela dépend des clients.
4) Puis-je apporter des modifications sans versionner ? Les ajouts généralement oui. Aucun retrait/modification.
5) Comment signaler une dépréciation ? En-têtes, documents, e-mails, période de transition.
A lire aussi
- GraphQL pour Applications : Guide de mise en œuvre -Backend pour les applications : architecture, technologies et bonnes pratiques -Microservices dans les applications : architecture distribuée pour mobile
- API pour les applications -API pour les applications - Étape par étape dans la vie quotidienne
- API pour les applications - Étape par étape vers la mise à l'échelle