Lorsque l'API évolue activement, il est important de maintenir la compatibilité entre les versions et d'éviter les situations où un seul changement brise des dizaines d'intégrations de clients. Nous mettons en œuvre une version complète des contrats pour contrôler les modifications et mettre à jour l'API sans risque pour les utilisateurs.
C'est essentiel dans l'architecture microservices, les intégrations B2B et les produits API ouverts, où différents clients utilisent des versions différentes des interfaces.
Ce que nous versionnons
| Objet | Description |
|---|---|
| Spécifications OpenAPI | Nous conservons toutes les versions de la documentation et du contrat |
| Endpoint'ы | Nous ajoutons des versions à l'URL ('/v1/', '/v2/'), conservons la compatibilité backward |
| Contrats (Pact, Dredd) | Fixation des conditions d'interaction client-serveur |
| Modèles de données | Contrôle des modifications apportées à la structure de la requête et de la réponse |
Comment nous réalisons
Prise en charge de plusieurs versions de l'API en parallèle
Spécification explicite de la version dans l'URL, les titres ou les options
Autotest de chaque version des contrats (Pact, Postman, Jest, Dredd)
Versioner les spécifications en Git ou via CI/CD
Documentation et changelog pour les clients à chaque changement
Avantages
Stabilité garantie des intégrations
Possibilité de produire de nouvelles fiches sans risque de « casser » les clients
Faciliter la migration entre les versions
Historique clair des modifications et contrôle des contrats
Transparence pour les équipes de développement externes et internes
Où est particulièrement important
Architecture microservices multi-dépendances
Plates-formes avec API publique ou B2B
Systèmes financiers et de paiement avec contrats à long terme
Applications mobiles dépendantes d'une API stable
Le versioning contractuel est la base de la prévisibilité et de la confiance dans l'API. Nous introduisons des processus qui permettent de changer et de développer l'API sans douleur, tout en maintenant l'interopérabilité et la transparence pour toutes les parties.