Versionnage d'API REST : URL, en-tête ou query, que choisir

Le versionnage d’API REST est la façon dont une API indique à un appelant quel contrat une requête utilise, pour que le serveur puisse changer le contrat sans casser les appelants qui n’ont pas bougé. La version peut aller à trois endroits : le chemin de l’URL (/v2/orders), un en-tête de requête (Accept: application/vnd.acme.v2+json ou un en-tête maison Api-Version: 2026-10-01), ou un paramètre de requête (/orders?version=2). Le chemin est le plus courant parce qu’il est visible partout, l’en-tête est le plus propre pour l’URL, et la query string est celle que la plupart des équipes regrettent. Le bon choix dépend de qui sont vos appelants et de la façon dont vous comptez leur annoncer les changements.

Que sont v1 et v2 dans une API REST ?

v1 et v2 sont les étiquettes de deux versions du contrat d’API : les mêmes ressources, accessibles à des chemins différents, où v2 peut renommer des champs, changer des types, retirer des endpoints ou modifier des formes d’erreur dont les appelants v1 dépendent. Une requête vers /v1/orders continue de recevoir l’ancienne forme tant que v1 est supportée ; une requête vers /v2/orders reçoit la nouvelle. Le numéro est une promesse de compatibilité, et c’est cette promesse qui le rend utile. L’incrémenter à chaque release transforme l’étiquette en bruit.

La plupart des API n’ont besoin d’une nouvelle version majeure que pour un changement qui casse les appelants existants. Ajouter un champ, un nouvel endpoint ou un nouveau paramètre optionnel peut être livré sous la version actuelle, parce qu’un client bien écrit ignore ce qu’il ne connaît pas. Quand versionner une API, et que faire à la place couvre la décision ; cet article traite de l’endroit où placer la version dans le versionnage d’API REST une fois que vous avez décidé de l’incrémenter.

Le versionnage d’API REST doit-il aller dans l’URL ou dans un en-tête ?

Mettez-le dans l’URL si vos appelants comptent des gens qui tapent des requêtes dans un navigateur, copient des exemples depuis la documentation ou lisent des logs ; mettez-le dans un en-tête si vous voulez une URL stable par ressource et que vos appelants sont tous des SDK ou du code que vous contrôlez. Le chemin de l’URL est explicite comme rien d’autre ne l’est : un ticket de support qui contient la ligne de requête vous donne déjà la version. Un en-tête doit être envoyé à chaque requête, est invisible dans un lien et se perd facilement sur un proxy, raison pour laquelle les API versionnées par en-tête définissent toujours un défaut pour les requêtes qui n’en envoient pas.

L’approche par en-tête a un vrai avantage au-delà des URL propres : elle sépare l’identité de la ressource de sa représentation, ce qui est la façon dont HTTP a été conçu. La RFC 9110 décrit la négociation de contenu via Accept, et un type de média comme application/vnd.github.v3+json est une version exprimée ainsi. En pratique, la pureté de la conception compte moins que la question de savoir si vos appelants pensent à envoyer l’en-tête.

Comment fonctionne le versionnage par date ?

Au lieu de v1 et v2, la version est une date, et chaque changement cassant reçoit une nouvelle date. Un appelant fixe la date contre laquelle il s’est intégré, en général une fois au niveau du compte, et garde ce comportement jusqu’à ce qu’il choisisse de bouger. L’en-tête Stripe-Version de Stripe et X-GitHub-Api-Version de GitHub fonctionnent tous deux ainsi.

Le compromis se trouve dans l’implémentation. Chaque changement cassant devient une petite couche de transformation qui convertit entre la date fixée et la forme actuelle, et le serveur les empile : une requête fixée deux ans en arrière traverse chaque changement intervenu depuis. C’est plus lourd à construire qu’une seconde copie des handlers, et cela récompense une API qui change rarement. Les équipes qui livrent un changement cassant par mois finissent avec des dizaines de transformations. Le versionnage de l’API Stripe examine le modèle du côté de l’appelant, y compris ce que le changelog doit porter.

Pourquoi le versionnage par query string est-il déconseillé ?

Parce qu’il mélange le contrat avec les filtres. /orders?status=open&api-version=2 fait passer la version pour un raffinement optionnel plutôt que pour ce qui décide de la forme de chaque champ de la réponse. C’est aussi la plus facile à perdre par accident, puisque les query strings sont reconstruites par les bibliothèques clientes, retirées par certains proxies et modifiées à la main par des gens. Le guide de conception d’API REST de Microsoft documente la forme en paramètre de requête qu’Azure utilise, et c’est l’écosystème de SDK générés autour qui la rend viable ; sans cet outillage, un appelant qui oublie le paramètre reçoit silencieusement la version par défaut.

Qu’advient-il de l’ancienne version ?

Elle continue de tourner, avec une date à laquelle elle s’arrête. Le but du versionnage est de laisser les appelants migrer selon leur propre calendrier, et ce n’est vrai que si l’ancienne version reste disponible assez longtemps pour cela et qu’on leur dit quand elle prend fin. Le guide de versionnage d’API de Google décrit le cycle de vie qu’il applique à ses propres API : une version stable est supportée jusqu’à une date de dépréciation publiée, avec le remplacement disponible pendant toute la fenêtre de dépréciation.

L’annonce est la partie que la plupart des équipes négligent. Un nouveau chemin ou un nouvel en-tête ne sert qu’aux appelants qui savent qu’il existe, savent ce qui a changé et savent quand v1 disparaît. Ce sont trois faits, et chacun a besoin d’un endroit : une entrée datée dans le changelog d’API avec les différences champ par champ, un avis de dépréciation qui indique la date de fin, et un guide de migration qui passe en revue chaque changement pour un appelant encore sur l’ancienne version. Mettre fin à une version d’API couvre la dernière étape, y compris l’en-tête Sunset qui permet à un client de découvrir la date sur chaque réponse.

Peut-on éviter totalement le versionnage d’API REST ?

Oui, tant que chaque changement est additif. Ajoutez des champs, n’en retirez ni n’en renommez jamais ; ajoutez des endpoints, ne changez jamais ce qu’un endpoint existant renvoie ; acceptez de nouveaux paramètres optionnels, ne changez jamais le sens d’un ancien. Beaucoup d’API internes tournent des années sur cette seule règle, et c’est celle que suivent les schémas GraphQL par conception. Le coût est un contrat qui ne fait que grossir, avec des champs dépréciés qui doivent rester parce que quelqu’un, quelque part, les lit encore.

Quand un changement additif est impossible, la version est l’outil. Le choix entre chemin, en-tête et date décide de ce que voient les appelants et de la façon dont le changement est annoncé ; ce qui reste constant, c’est que le changement doit être écrit quelque part où un appelant le lira. Pour une API avec des appelants externes, cet endroit est le changelog, et l’article sur les changements cassants explique ce qui en est un.

FAQ

Quelle est la meilleure façon de versionner une API REST ? Une version majeure dans le chemin de l’URL est la plus largement comprise et la plus difficile à rater, ce qui en fait le choix par défaut pour une API publique. Une version en en-tête garde les URL stables et convient aux API pilotées par des SDK ; un en-tête daté convient aux API qui changent rarement et veulent que les appelants fixent un comportement.

Que signifie v1 dans une URL d’API ? C’est la première version majeure du contrat d’API. Les requêtes vers /v1/... ont la garantie de recevoir la forme documentée pour la version 1, même après l’apparition d’un /v2/ avec des champs ou un comportement différents.

Faut-il une nouvelle version d’API à chaque changement ? Non. Les changements additifs comme de nouveaux champs, endpoints et paramètres optionnels peuvent être livrés sous la version existante. Seul un changement qui casse les appelants existants en demande une nouvelle.

Combien de temps faut-il supporter une ancienne version d’API ? Assez longtemps pour que les appelants migrent, ce qui pour une API publique est en général six à douze mois après la disponibilité du remplacement, avec la date publiée à l’annonce et répétée dans l’avis de dépréciation.

Les affirmations techniques de cet article n'ont pas été vérifiées de façon indépendante. Si quelque chose est faux, dis-le-nous et nous le corrigerons.

À voir sur changeloop : Documentation développeurs, Exemples de changelog