Versions

Une API se doit de garantir un maximum de stabilité concernant son contrat de service.

Pour éviter de casser un contrat et provoquer ainsi des erreurs au niveau des consommateurs, il existe deux techniques :

• Profiter des possibilités d'extension du flux JSON en respectant son schéma
• Délivrer une nouvelle version de l'API tout en maintenant l'ancienne pour permettre une migration douce des clients

Conseil : éviter de maintenir trop de versions différentes, limiter autant que possible à deux versions (l'actuelle et la précédente)

doitRespecter le principe de rétro-compatibilité tel que spécifié par le versioning sémantique.

Il y a différentes façons de négocier, entre le client et le serveur, la version de l'API à consommer :

1. URL : la version fait partie d'un préfixe d'URL (exemple : https://api.laposte.fr/masuperapi/v2/), pas idéal sémantiquement (la localisation de la ressource devient dépendante de la version) mais très facile à utiliser
2. Un en-tête de requête custom (exemple : API-Version) : pas idéal du point de vue du respect des specs HTTP (réinvention de la roue)
3. l'en-tête de requête Accept : convention du format compliquée, pénible à traiter (application/vnd.masuperapi.v2+json)
4. Aucun : toujours considérer la dernière version, avec le risque d'instabilité du contrat
5. Mix : supporter l'URL et les en-têtes pour, par exemple, pouvoir préciser une version mineure (démarche luxueuse)

optionLa solution 1 n'est pas idéale mais est facilement maîtrisée et simple à apréhender, c'est pourquoi elle est le plus souvent privilégiée.

La version exposée par l'API n'est pas nécessairement corrélée avec la version interne du produit, qui généralement respecte les principes de la versioning sémantique.

optionPour indiquer aux clients qu'une version est dépréciée, il est bienvenu d'utiliser des en-têtes de réponses X-API-Version et X-API-Warn afin de le prévenir.