Versioning de vos API

Afin de gérer les évolutions que vous apportez à vos API (Oauth2 par exemple), il est nécessaire de prévoir un versioning de celles-ci. Il doit être prévu dès la mise en place des API afin d’éviter de lourds impacts à vos consommateurs.

Types de modification d’une API

Il faut distinguer plusieurs types de modifications apportées à une API :

• sans changement du contrat d’interface : les évolutions sont transparentes pour les utilisateurs de l’API. Les paramètres d’entrée et de sortie restent identiques.
• avec l’ajout de paramètres en entrée et / ou en sortie : le contrat d’interface est alors modifié mais les utilisateurs actuels ne sont pas impactés car les paramètres déjà en place restent utilisables.
• avec la modification ou la suppression de paramètre en entrée ou en sortie : le contrat d’interface est modifié et tout ou partie des consommateurs sont impactés.

Dans les deux premiers cas, nous parlons d’une modification de version mineure car elle n’a pas d’impact sur les utilisateurs de l’API. En revanche, dans le dernier cas, il s’agit d’une modification de version majeure : c’est ce type de modification qui doit amener à l’incrément de la version de l’API.

Type de versioning d’API

Il est possible de gérer le versioning d’une API de plusieurs manières différentes : classiquement par numéro de version (v1, v2, etc.) mais également par date. Cette dernière façon peut permettre de basculer automatiquement dans une nouvelle version en fonction de la date de l’appel. Par exemple, vous pouvez décider qu’au 01/03/20, l’API fonctionnera avec son nouveau contrat d’interface. Attention, cela a un fort impact sur les consommateurs de l’API : ils doivent mettre en place les modifications inhérents au nouveau contrat d’interface en même temps que la bascule.

Le plus conseillé est donc de gérer un numéro de version.

Gestion du versioning d’une API

Le numéro de version peut être “envoyée” à l’API de plusieurs façons :

• Dans l’URL d’appel
• En paramètres de la requête
• Vai les headers de la requête

Le numéro de version peut être facultatif : ainsi, s’il n’est pas renseigné, un numéro de version par défaut est appliqué. Attention cependant, en utilisant un numéro de version par défaut, lors d’un changement de celui-ci, les utilisateurs de l’API qui ne renseignent pas ce numéro sont donc forcément impactés.

Il est donc d’usage de faire du numéro de version un élément obligatoire.

Exemples de versioning d’API

Prenons une exemple de versioning d’une API listant les clients. Selon la gestion du numéro de version choisie, l’URL d’appel est différente. Dans le cas d’une modification de version mineure (sans modification ou suppression d’un paramètre existant de l’API), ces URL restent identiques. Dans le cas contraire, les URL d’appels doivent alors évoluer.

Version dans l’URL d’appel

• V1 : https://api.exemple.fr/v1/clients
• V2 : https://api.exemple.fr/v2/clients

Version en paramètre de la requête

• V1 : https://api.exemple.fr/clients?version=1
• V2 : https://api.exemple.fr/clients?version=2

Version en header de la requête

• V1 : https://api.exemple.fr/clients avec le header version: 1
• V2 : https://api.exemple.fr/clients avec le header version: 2

Communication aux consommateurs des API

L’ajout d’une nouvelle version doit être communiqué aux utilisateurs de la version précédente de l’API. Il est d’usage de leur laisser un temps raisonnable afin de passer vers la nouvelle version.

A la fin de cette période, la version précédente devient alors indisponible. Pendant toute cette période, la maintenance peut alors être double : une correction à apporter à l’ancienne version peut être applicable à la nouvelle et vice-versa.

Il n’est donc pas conseillé d’avoir plus de deux versions à maintenir en parallèle afin de ne pas complexifier la maintenance de l’API et d’éviter tout risque de dysfonctionnement en production.