ESENPTFR
Contact
Changer de langue
ESENPTFR

Versionnage des API

Stratégies pour versionner les API REST et GraphQL — versionnage par URL, en-têtes, sémantique, compatibilité ascendante et dépréciation.

Pourquoi versionner les API ?

Lorsque plusieurs consommateurs dépendent d’une API, tout changement de son contrat peut casser des intégrations existantes. Le versionnage permet de faire évoluer l’API de manière contrôlée, en laissant aux consommateurs le temps de s’adapter.

Sans stratégie de versionnage claire, les équipes se retrouvent dans l’une de ces deux situations : soit elles n’osent plus rien changer de peur de casser des consommateurs, soit elles cassent des choses en permanence sans s’en rendre compte.

Stratégies de versionnage

Versionnage par URL

La stratégie la plus courante et la plus visible. La version est incluse directement dans le chemin :

GET /api/v1/products
GET /api/v2/products

Avantages :

  • Extrêmement explicite — aucune ambiguïté sur la version utilisée
  • Facile à router dans les API Gateways et les load balancers
  • Simple à documenter et à communiquer

Inconvénients :

  • Peut entraîner une duplication de code si la structure interne n’est pas bien pensée
  • Les consommateurs doivent mettre à jour les URLs lors de la migration

Versionnage par en-têtes

La version est spécifiée dans un en-tête HTTP personnalisé ou dans l’en-tête Accept :

GET /api/products
Accept: application/vnd.myapi.v2+json

Ou avec un en-tête personnalisé :

GET /api/products
X-API-Version: 2

Avantages :

  • Les URLs restent propres et stables
  • Permet une négociation de contenu plus sophistiquée

Inconvénients :

  • Moins visible — il faut inspecter les en-têtes pour savoir quelle version est utilisée
  • Plus difficile à tester depuis un navigateur

Versionnage sémantique (SemVer)

Applique les principes du Semantic Versioning à l’API :

  • MAJOR (v1 → v2) : Changements incompatibles avec les versions précédentes (breaking changes)
  • MINOR (v1.1 → v1.2) : Nouvelles fonctionnalités rétrocompatibles
  • PATCH (v1.1.0 → v1.1.1) : Corrections de bugs sans changement fonctionnel

En pratique, les API publiques n’exposent généralement que la version MAJOR dans l’URL (/v1/, /v2/) et gèrent les MINOR/PATCH en interne.

Compatibilité ascendante

Un changement est rétrocompatible (backward compatible) si les consommateurs existants peuvent continuer à fonctionner sans modification. Exemples de changements compatibles :

  • Ajouter un nouveau champ optionnel à une réponse
  • Ajouter un nouvel endpoint
  • Ajouter un paramètre de requête optionnel
  • Ajouter une nouvelle valeur à un enum (avec précaution)

Exemples de changements breaking :

  • Supprimer un champ de la réponse
  • Renommer un champ existant
  • Changer le type d’un champ (string → number)
  • Rendre obligatoire un champ qui était optionnel
  • Modifier la sémantique d’un champ existant

Stratégies de dépréciation

Lorsque vous devez retirer une ancienne version :

1. Communication anticipée

Annoncez la dépréciation suffisamment à l’avance (minimum 3 à 6 mois pour les API publiques) :

Deprecation: true
Sunset: Sat, 01 Mar 2025 00:00:00 GMT
Link: <https://docs.api.com/migration/v2>; rel="successor-version"

2. Période de coexistence

Maintenez les deux versions actives en parallèle pendant la période de transition. Surveillez le trafic de l’ancienne version pour savoir quand il est possible de la retirer en toute sécurité.

3. Réponses avec avertissements

Incluez des en-têtes d’avertissement dans les réponses de la version dépréciée :

Warning: 299 - "API v1 is deprecated. Please migrate to v2 by 2025-03-01"

4. Sunset définitif

Une fois la date de sunset dépassée, les appels vers l’ancienne version peuvent renvoyer 410 Gone avec un corps de réponse expliquant comment migrer.

Bonnes pratiques

  • Versionnez dès le premier jour — il est bien plus simple de commencer avec /v1/ que d’ajouter le versionnage après coup
  • Documentez les changements — maintenez un changelog clair par version
  • Utilisez des feature flags en interne — pour gérer les différences entre versions sans dupliquer le code
  • Surveillez l’utilisation par version — sachez combien de consommateurs utilisent chaque version avant de la déprécier
  • Définissez une politique de support — combien de versions vous maintenez simultanément et pendant combien de temps