API VERSIONING STRATEGY

Preface

Qu’on soit un developpeur experimente ou debutant, des fois, on developpe des APIs pour fournir des services vers d’autres applications. Mais, si un jour vous decidez de changer la reponse, ou la requete attendue ou meme le endpoint? Que se passe-t-il pour les applications utilisant l’ancienne version de ton API?

Je vais vous presenter 4 facon de resoudre ce probleme:

  • L’URL versioning
  • L’accept headers versioning
  • Hostname versioning
  • Et enfin, query param versioning

Ne vous inquietez pas si tout semble flou, nous allons y aller un a un.

NOTICE GENERALE

Pour chaque approche, vous devez définir une logique dans votre action de traitement de chaque demande pour:

  • Si la version n’existe pas?
  • Si l’action n’est pas définie, le mieux est de définir une action par défaut pour la gérer. Par exemple, vous avez une interface qui contient toutes les versions disponibles de l’API. Si la version est pas spécifiée par le client, vous renvoyez tout simplement l’action par défaut
    L’action par défaut peut être une exception qui avertit le client que la version de l’API qu’il souhaite appeler n’est pas disponible ou renvoie simplement une valeur par défaut.

URL VERSIONING

Supposons que votre API possède des versions telles que: v1, v2, v3. Avec URL VERSIONING, la demande que vous allez recevoir sera comme:

GET /v1/action/ HTTP/1.1
Host: host.com
Accept: application/json

L’avantage de cette approche est que l’URL est plus significative et plus facile à gérer

MAIS!,
Si vous n’avez pas encore pensé à la gestion de version de votre API et que vous aviez une URL comme hôte / api?, Le style d’URL précédent ne pourra pas gérer cela. Ce n’est pas la meilleure solution pour votre cas

ACCEPT HEADERS VERSIONING

Dans de nombreux cas, les API et les consommateurs utilisent JSON ou XML pour échanger des données. Cette approche utilise le paramètre request pour spécifier la version du client API à consommer en tant que demande d’acceptation PARAM. Par exemple:

GET /api/ HTTP/1.1
Host: host.com
Accept: application/details.json; version=1.0

HOSTNAME VERSIONING

Cette approche nécessite la création d’un sous-domaine pour chaque version de l’API. nous ne faisons pas référence au nom de l’action pour cette approche, mais par le sous-domaine de la version de l’API.

GET /api/ HTTP/1.1
Host: v1.host.com
Accept: application/json

QUERY PARAM VERSIONING

Le client doit simplement indiquer la version de l’API qu’il souhaite utiliser, par exemple:

 

GET /api/?version=v1 HTTP/1.1
Host: host.com
Accept: application/json

 

Mot de la fin

Chaque approche presente des avantages et incovenients selon votre contexte. Assurez-vous de faire le bon choix avant de se lancer vraiment dans le versioning de votre API

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *