Versionner une API n'est pas optionnel dès lors que vous avez des clients externes. Mais quelle stratégie choisir ? URI, headers, paramètre de requête ? Voici les compromis de chaque approche.
Le versioning d'API est l'une de ces décisions techniques qui semblent anodines au départ et qui peuvent devenir un cauchemar de maintenance à mesure que l'API grandit. La règle fondamentale : ne jamais introduire de breaking changes sans versionner. Supprimer un champ, renommer une propriété, changer un type — tout cela casse les clients existants sans préavis. Ajouter un champ optionnel, en revanche, est généralement rétrocompatible.
Trois stratégies principales existent. Le versioning par URI (/api/v1/users) est le plus explicite et le plus
lisible. Chaque version est une URL distincte, facile à router, à cacher, à documenter séparément. C'est la plus
répandue et celle que nous recommandons pour la plupart des cas. Le versioning par header (Accept: application/vnd.myapi.v2+json) est plus « pur » REST mais moins pratique à utiliser et à déboguer. Le versioning par
paramètre de requête (?version=2) est simple mais pollue les URLs et les logs.
La vraie question n'est pas comment versionner mais quand déprécier. Une fois publiée, une version d'API crée une dette. Il faut une politique claire : période de support minimale, communications aux clients, logs de l'utilisation des anciennes versions pour identifier les clients à migrer. L'idéal est d'éviter la prolifération de versions en faisant évoluer l'API de façon additive le plus longtemps possible — et de limiter les breaking changes aux vrais besoins architecturaux.
- Préférez le versioning par URI pour sa simplicité
- Définissez dès le départ votre politique de dépréciation
- Monitorez l'utilisation de chaque version en production
- Communiquez les breaking changes bien à l'avance