Toujours dans la logique de réfléchir son API, parce qu’un jour il faudra la faire évoluer, comment gérer le versionnement ?
Plusieurs solutions ont émergé :
- https://api-v2.example.com/maressource
- https://api.example.com/v2/maressource
- https://api.example.com/maressource-v2
- https://api.example.com/maressource?v=2
- https://api.example.com/maressource avec une entête Version: 2
- https://api.example.com/maressource avec une entête Accept ou/et Content-type: application/monformat;version=2
La solution du sous-domaine n’est à mon sens à réserver que pour les big-bang. Elle n’est pas facilement multipliable à l’infini, mais à l’avantage de permettre aisément d’avoir même deux plateformes totalement séparées pour les deux versions de l’API.
Les deux suivantes se distinguent par le fait de versionner l’API ou la ressource. J’ai tendance à penser que s’il faut versionner la ressource en cassant la compatibilité, alors c’est peut être une nouvelle version de l’API qui est à publier si on ne veut pas finir avec un gros patchwork difficile à maintenir : En gardant tout sous le même espace on s’interdit de facilement rendre obsolète les anciennes versions.
Quitte à parfois devoir versionner au niveau de la ressource, l’idée d’ajouter un paramètre a fini par me sembler plus propre. Il s’agit quasiment toujours de s’adresser à une représentation différente de la ressource, pas de changer son sens fondamental. Le risque est que la plupart des gens continuent à utiliser la version d’origine et ne pas prendre en compte le paramètre. Rendre obsolète des anciennes représentations risque là aussi d’être difficile.
Les possibilités d’ajouter les versions dans les entêtes sont souvent conseillées d’un point de vue théorique. En pratique mon retour est que c’est complexe à utiliser, et d’une valeur ajoutée assez discutable. On oublie trop facilement que le bon usage de l’API tient directement à sa simplicité et sa bonne compréhension. S’il y a besoin d’être expert en architecture web pour comprendre le pourquoi des choses, c’est une mauvaise solution. Le « tout dans l’URL » ajoute une facilité pour tester et échanger entre techniciens qui vaut toutes les positions académiques du monde.
Twilio a aussi une façon intéressante de gérer les versions. Au lieu d’un v2 ou v3, le développeur indique une date et c’est le serveur qui sélectionne la version de l’API à utiliser en fonction de la date. C’est tentant, souple, mais j’ai peur que ce ne soit pas suffisamment explicite sur ce qu’on utilise ou sur comment gérer ce paramètre. Qu’est-ce qui change si je met à jour la date ?
Des lectures et expériences je tire quelques recommandations :
- Prévoir dès le départ un système de versionnement, vous en aurez besoin un jour, ne croyez pas que vos API pourront rester telles quelles ad vitam eternam
- Imposer un versionnement explicite, immédiatement, dès la première version. Vous éviterez les ambiguïtés et une partie des moules qui s’attachent aux adresses « sans version » par défaut
- N’utiliser que des numéros de version simples, pas de notion de mineur/majeur, pas de points ou virgules : Si ça change de façon non compatible c’est une nouvelle version et on incrémente d’une unité. Le reste c’est du marketing et ça n’a rien à faire dans vos URLs.
- Utiliser un versionnement dans l’URL, à la racine du service ; il sera temps d’utiliser un autre sous-domaine si un jour il y a un vrai big bang qui le nécessite
- Documenter (oui, c’est évident, mais pas si simple à ne pas oublier)
Laisser un commentaire