Quelle est la meilleure stratégie de gestion de version d'API : URL, En-tête ou Négociation de contenu ?

TL;DR

Le versionnement par URL (/v1/pets) est la stratégie de versionnement d'API la plus pratique pour la plupart des équipes. Elle est visible, cacheable et facile à tester. Le versionnement par en-tête et la négociation de contenu sont plus « purs » REST mais ajoutent de la complexité. Modern PetstoreAPI utilise le versionnement par URL avec le versionnement sémantique et des politiques de dépréciation claires.

Introduction

Votre API nécessite une modification incompatible. Vous modifiez le format de réponse pour /pets d'un simple tableau à un objet enveloppé avec des métadonnées de pagination. Les clients existants cesseront de fonctionner. Que faites-vous ?

Vous avez besoin du versionnement d'API. Mais quelle stratégie ? Le versionnement par URL (/v1/pets vs /v2/pets) ? Le versionnement par en-tête (Accept: application/vnd.petstore.v1+json) ? La négociation de contenu ? Chaque approche a des défenseurs passionnés et des opinions tranchées.

La réponse : le versionnement par URL l'emporte pour la plupart des équipes. Il est pragmatique, visible et fonctionne avec tous les outils HTTP. Le versionnement par en-tête et la négociation de contenu sont théoriquement plus propres mais ajoutent une complexité dont la plupart des équipes n'ont pas besoin.

Modern PetstoreAPI utilise le versionnement par URL avec le versionnement sémantique et des politiques de dépréciation claires. La version actuelle est v1, avec v2 prévue pour les futures modifications incompatibles.

💡

Si vous créez ou testez des API REST, Apidog vous aide à tester plusieurs versions d'API, à valider les comportements spécifiques à chaque version et à garantir la compatibilité ascendante. Vous pouvez maintenir des spécifications distinctes pour chaque version et exécuter des tests sur toutes les versions simultanément.

bouton

Dans ce guide, vous découvrirez les trois principales stratégies de versionnement, leurs compromis et comment implémenter correctement le versionnement en utilisant Modern PetstoreAPI comme référence.

Pourquoi les API ont besoin de versionnement

Les API évoluent. Vous ajoutez des fonctionnalités, corrigez des bugs et améliorez les conceptions. Parfois, ces changements rompent la compatibilité avec les clients existants.

Modifications incompatibles

Modifications qui rompent la compatibilité avec les clients existants :

1. Suppression de champs :

// v1
{"id": "123", "name": "Fluffy", "age": 3}

// v2 (breaking: removed age)
{"id": "123", "name": "Fluffy"}

2. Modification des types de champs :

// v1
{"price": "19.99"}

// v2 (breaking: string to number)
{"price": 19.99}

3. Modification de la structure de réponse :

// v1 (bare array)
[{"id": "123"}]

// v2 (breaking: wrapped object)
{"data": [{"id": "123"}], "pagination": {...}}

4. Modification de la structure d'URL :

// v1
GET /pet/123

// v2 (breaking: plural)
GET /pets/123

5. Modification de l'authentification :

// v1: API key in query
GET /pets?api_key=xxx

// v2 (breaking: Bearer token)
GET /pets
Authorization: Bearer xxx

Modifications non-incompatibles

Modifications qui ne rompent pas la compatibilité avec les clients :

Ajout de nouveaux points d'accès
Ajout de champs facultatifs aux requêtes
Ajout de nouveaux champs aux réponses (les clients doivent ignorer les champs inconnus)
Ajout de nouveaux paramètres de requête
Ajout de nouvelles méthodes HTTP aux ressources existantes

La décision de versionnement

Lorsque vous avez besoin d'une modification incompatible, vous avez deux options :

1. Forcer tous les clients à mettre à jour - Simple mais rompt les intégrations existantes

2. Supporter plusieurs versions - Plus de travail mais maintient la compatibilité ascendante

La plupart des API publiques choisissent l'option 2. Le versionnement vous permet de faire évoluer l'API tout en donnant aux clients le temps de migrer.

Versionnement par URL

Le versionnement par URL place le numéro de version dans le chemin de l'URL.

Comment ça fonctionne

GET /v1/pets
GET /v2/pets

La version fait partie de l'identifiant de la ressource. Différentes versions sont des ressources différentes.

Avantages

1. Visible et explicite

La version est dans l'URL. Vous pouvez la voir dans les journaux, l'historique du navigateur et la documentation. Aucun en-tête caché à retenir.

2. Facile à tester

curl https://petstoreapi.com/v1/pets
curl https://petstoreapi.com/v2/pets

Vous pouvez tester les deux versions avec de simples requêtes HTTP.

3. Fonctionne avec tous les outils HTTP

Les navigateurs, caches, proxys et équilibreurs de charge voient différentes URL. Ils peuvent router, mettre en cache et journaliser chaque version indépendamment.

4. Simple pour les clients

Les clients changent simplement l'URL. Pas d'en-têtes personnalisés ni de logique de négociation de contenu.

5. Facile à déprécier

Vous pouvez supprimer les points d'accès /v1 sans affecter /v2.

Inconvénients

1. Pas « pur » REST

Les puristes REST soutiennent que /v1/pets/123 et /v2/pets/123 sont la même ressource, ils devraient donc avoir la même URL. La version devrait être dans les en-têtes ou la négociation de contenu.

2. Pollution d'URL

Votre API a plusieurs espaces d'URL : /v1/*, /v2/*, etc.

3. Plus difficile de versionner des ressources individuelles

Si vous souhaitez versionner un seul point d'accès, vous devez versionner toute l'API ou créer une incohérence.

Implémentation

Version majeure dans l'URL :

/v1/pets
/v2/pets

N'incluez pas les versions mineures :

❌ /v1.2/pets  (trop granulaire)
✅ /v1/pets    (version majeure uniquement)

Utilisez le versionnement sémantique en interne :

v1.0.0 - Version initiale
v1.1.0 - Ajout de nouveaux champs (non-incompatible)
v1.2.0 - Ajout de nouveaux points d'accès (non-incompatible)
v2.0.0 - Modifications incompatibles (nouvelle URL : /v2)

Modern PetstoreAPI utilise le versionnement par URL avec /v1 comme version actuelle.

Versionnement par en-tête

Le versionnement par en-tête place la version dans un en-tête HTTP personnalisé.

Comment ça fonctionne

GET /pets
API-Version: 1

GET /pets
API-Version: 2

L'URL reste la même. L'en-tête spécifie la version.

Avantages

1. URL propres

/pets est le même pour toutes les versions. Pas de préfixe /v1 ou /v2.

2. Plus « RESTful »

L'identifiant de ressource (/pets/123) ne change pas. La représentation change en fonction de l'en-tête.

3. Versionnement granulaire

Vous pouvez versionner des ressources individuelles :

GET /pets
API-Version: 2

GET /orders
API-Version: 1

Inconvénients

1. Invisible

La version n'est pas dans l'URL. Vous ne pouvez pas la voir dans les journaux ou l'historique du navigateur sans vérifier les en-têtes.

2. Plus difficile à tester

curl -H "API-Version: 1" https://petstoreapi.com/pets
curl -H "API-Version: 2" https://petstoreapi.com/pets

Vous devez vous souvenir d'inclure l'en-tête.

3. Complexité du cache

Les caches doivent prendre en compte l'en-tête API-Version. Vous avez besoin de Vary: API-Version dans les réponses.

4. Complexité côté client

Les clients ont besoin d'une logique d'en-tête personnalisée. Tous les clients HTTP ne facilitent pas cela.

5. Ambigüité de la version par défaut

Que se passe-t-il si le client n'envoie pas l'en-tête ? Vous avez besoin d'une valeur par défaut, ce qui crée un comportement implicite.

Implémentation

En-tête personnalisé :

API-Version: 1

Ou utilisez l'en-tête Accept :

Accept: application/vnd.petstore.v1+json

Incluez l'en-tête Vary :

Vary: API-Version

Cela indique aux caches de prendre en compte l'en-tête lors de la mise en cache.

Négociation de contenu

La négociation de contenu utilise l'en-tête Accept avec des types de médias personnalisés.

Comment ça fonctionne

GET /pets
Accept: application/vnd.petstore.v1+json

GET /pets
Accept: application/vnd.petstore.v2+json

La version fait partie du type de média.

Avantages

1. Le plus « RESTful »

C'est ainsi que REST a été conçu. Différentes représentations de la même ressource.

2. Suit les standards HTTP

Utilise la négociation de contenu HTTP standard.

3. Prend en charge plusieurs formats

Vous pouvez versionner et formater simultanément :

Accept: application/vnd.petstore.v1+json
Accept: application/vnd.petstore.v1+xml

Inconvénients

1. Complexe

Les clients doivent comprendre les types de médias et la négociation de contenu.

2. Plus difficile à tester

curl -H "Accept: application/vnd.petstore.v1+json" https://petstoreapi.com/pets

3. Mauvais support des outils

De nombreux clients HTTP et outils ne gèrent pas bien les types de médias personnalisés.

4. Complexité du cache

Les caches doivent prendre en compte l'en-tête Accept. Vous avez besoin de Vary: Accept.

5. Excès pour la plupart des API

La plupart des API n'ont pas besoin de ce niveau de sophistication.

Implémentation

Type de média spécifique au fournisseur :

Accept: application/vnd.petstore.v1+json

Réponse :

Content-Type: application/vnd.petstore.v1+json
Vary: Accept

Comment Modern PetstoreAPI implémente le versionnement

Modern PetstoreAPI utilise le versionnement par URL avec des politiques claires.

Version actuelle : v1

https://petstoreapi.com/v1/pets
https://petstoreapi.com/v1/orders
https://petstoreapi.com/v1/users

Tous les points d'accès sont sous /v1.

En-tête de réponse de version

Chaque réponse inclut la version de l'API :

X-API-Version: 1.2.0

Cela affiche la version exacte (majeure.mineure.patch) même si l'URL n'affiche que la version majeure.

Avertissements de dépréciation

Lorsqu'une version est dépréciée, les réponses incluent :

Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.petstoreapi.com/migration/v1-to-v2>; rel="deprecation"

Deprecation - Indique que la version est dépréciée
Sunset - Date à laquelle la version sera supprimée
Link - Guide de migration

Découverte de version

Le point d'accès racine liste les versions disponibles :

GET https://petstoreapi.com/

{
  "versions": [
    {
      "version": "v1",
      "status": "current",
      "docsUrl": "https://docs.petstoreapi.com/v1"
    }
  ]
}

Versionnement sémantique

Modern PetstoreAPI suit le versionnement sémantique en interne :

Majeure (v1, v2) - Modifications incompatibles, nouvelle URL
Mineure (v1.1, v1.2) - Nouvelles fonctionnalités, compatible ascendante
Patch (v1.1.1, v1.1.2) - Corrections de bugs, compatible ascendante

Seules les versions majeures apparaissent dans les URL.

Tester les versions d'API avec Apidog

Apidog vous aide à tester plusieurs versions d'API.

Importer plusieurs versions

Importez les spécifications OpenAPI pour chaque version :

petstore-v1.yaml → Environment: v1
petstore-v2.yaml → Environment: v2

Exécuter des tests sur toutes les versions

Créez des suites de tests qui s'exécutent sur les deux versions :

// Test v1
pm.environment.set("baseUrl", "https://petstoreapi.com/v1");
pm.sendRequest(pm.environment.get("baseUrl") + "/pets");

// Test v2
pm.environment.set("baseUrl", "https://petstoreapi.com/v2");
pm.sendRequest(pm.environment.get("baseUrl") + "/pets");

Valider le comportement spécifique à la version

Vérifiez que v1 et v2 se comportent différemment :

// v1 returns bare array
pm.test("v1 returns array", function() {
    pm.expect(pm.response.json()).to.be.an('array');
});

// v2 returns wrapped object
pm.test("v2 returns wrapped object", function() {
    pm.expect(pm.response.json()).to.have.property('data');
    pm.expect(pm.response.json()).to.have.property('pagination');
});

Vérifier les en-têtes de dépréciation

Vérifiez que les versions dépréciées incluent les en-têtes appropriés :

pm.test("Deprecated version includes headers", function() {
    pm.response.to.have.header("Deprecation");
    pm.response.to.have.header("Sunset");
});

Stratégie de dépréciation de version

Comment déprécier les anciennes versions sans casser les clients.

1. Annoncer la dépréciation tôt

Donnez aux clients un préavis d'au moins 6 à 12 mois :

Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT

2. Fournir un guide de migration

Documentez toutes les modifications incompatibles et comment migrer :

Link: <https://docs.petstoreapi.com/migration/v1-to-v2>; rel="deprecation"

3. Surveiller l'utilisation

Suivez quels clients utilisent encore les versions dépréciées :

X-API-Version: 1.2.0
X-Client-ID: abc123

Contactez directement les clients si nécessaire.

4. Arrêt progressif

Ne supprimez pas la version immédiatement :

Mois 1-6 : Annoncer la dépréciation
Mois 7-9 : Ajouter les en-têtes de dépréciation
Mois 10-11 : Réduire les limites de débit pour la version dépréciée
Mois 12 : Supprimer la version dépréciée

5. Conserver la documentation

Même après la suppression, conservez la documentation pour l'ancienne version. Les clients pourraient avoir besoin de s'y référer.

Conclusion

Le versionnement par URL est la stratégie de versionnement d'API la plus pratique pour la plupart des équipes. Elle est visible, facile à tester et fonctionne avec tous les outils HTTP. Le versionnement par en-tête et la négociation de contenu sont plus « purs » REST mais ajoutent de la complexité.

Modern PetstoreAPI utilise le versionnement par URL avec /v1 comme version actuelle, le versionnement sémantique en interne et des politiques de dépréciation claires. Cette approche équilibre le pragmatisme et une bonne conception d'API.

Utilisez Apidog pour tester plusieurs versions d'API, valider les comportements spécifiques aux versions et assurer des migrations fluides entre les versions.

bouton

FAQ

Dois-je utiliser le versionnement par URL ou par en-tête ?

Utilisez le versionnement par URL sauf si vous avez une raison spécifique de ne pas le faire. C'est plus simple, plus visible et plus facile à tester. Le versionnement par en-tête est plus « RESTful » mais ajoute une complexité dont la plupart des équipes n'ont pas besoin.

Combien de versions dois-je prendre en charge simultanément ?

Prenez en charge 2 versions maximum : la version actuelle et la précédente. En supporter davantage crée un fardeau de maintenance. Donnez aux clients 6 à 12 mois pour migrer, puis supprimez les anciennes versions.

Dois-je versionner à partir de v0 ou v1 ?

Commencez par v1. v0 implique une instabilité. Si votre API n'est pas suffisamment stable pour v1, ne la publiez pas encore publiquement.

Dois-je versionner chaque point d'accès ?

Non. Ne versionnez que lorsque vous apportez des modifications incompatibles. Si vous ajoutez de nouveaux points d'accès sans modifier les existants, vous n'avez pas besoin d'une nouvelle version.

Qu'en est-il des versions mineures dans les URL ?

N'incluez pas les versions mineures dans les URL. Utilisez /v1, pas /v1.2. Les versions mineures sont compatibles ascendante, donc les clients n'ont pas besoin de changer d'URL.

Comment gérer les bugs spécifiques à une version ?

Corrigez les bugs dans toutes les versions prises en charge. Si un bug n'existe que dans v1, corrigez-le dans v1. Ne forcez pas les clients à passer à v2 pour des corrections de bugs.

Dois-je utiliser le versionnement sémantique ?

Oui, en interne. Suivez les versions majeure.mineure.patch, mais n'exposez que les versions majeures dans les URL. Cela vous donne de la flexibilité pour les modifications non-incompatibles.

Que faire si je dois versionner un seul point d'accès ?

Avec le versionnement par URL, vous devrez versionner l'ensemble de l'API ou créer une incohérence. C'est un compromis. La plupart des équipes acceptent de versionner l'ensemble de l'API pour des raisons de simplicité.