Comment rendre vos API REST rétrocompatibles

Le transfert d'état de représentation, communément appelé REST, est un style architectural - un ensemble de contraintes utilisées pour implémenter des services sans état qui s'exécutent sur HTTP. Une API RESTful est une API conforme aux contraintes REST. Vous pouvez créer des API RESTful à l'aide de nombreux langages de programmation différents.

Le maintien de la compatibilité descendante entre les différentes versions de votre API est de la plus haute importance pour garantir que votre API restera compatible avec tous les clients qui la consomment. Cet article présente une discussion sur la façon dont vous pouvez maintenir la compatibilité descendante dans vos API RESTful.

Exemple de compatibilité API

Supposons que vous disposez d'une API en production qui est utilisée par différents clients. Désormais, si vous souhaitez ajouter plus de fonctionnalités à l'API, vous devez vous assurer que les clients qui utilisent l'ancienne API pourront utiliser soit la nouvelle API, soit l'ancienne. En d'autres termes, vous devez vous assurer que la fonctionnalité existante de l'API restera intacte pendant l'ajout de la nouvelle fonctionnalité.

Une API est rétrocompatible si un client (un programme écrit pour consommer l'API) qui peut fonctionner avec une version de l'API peut fonctionner de la même manière avec les futures versions de l'API. En d'autres termes, une API est rétrocompatible entre les versions si les clients doivent pouvoir travailler de manière transparente avec une nouvelle version de l'API.

Comprenons cela avec un exemple. Supposons que vous disposez d'une méthode API nommée GetOrders, comme indiqué dans l'extrait de code ci-dessous.

[HttpGet]

[Route ("GetOrders")]

 public IActionResult GetOrders (int customerId, int orderId = 0)

 {

   var result = _orderService.GetOrdersForCustomer (

                 customerId, orderId);

   return Ok (résultat);

 }

La méthode d'action GetOrders accepte un ID client et un ID de commande comme paramètres. Notez que le deuxième paramètre, orderID, est facultatif. La méthode privée GetOrdersForCustomer est donnée ci-dessous.

Liste privée GetOrdersForCustomer (int customerId, int orderId)

{

   // Écrivez le code ici pour renvoyer un ou plusieurs enregistrements de commande

}

La méthode GetOrdersForCustomer renvoie toutes les commandes d'un client si le orderId qui lui a été passé en tant que paramètre est 0. Si le orderId est différent de zéro, il renvoie une commande appartenant au client identifié par le customerId passé en argument.

Étant donné que le deuxième paramètre de la méthode d'action GetOrders est facultatif, vous pouvez simplement transmettre le customerId. Désormais, si vous modifiez le deuxième paramètre de la méthode d'action GetOrders pour le rendre obligatoire, les anciens clients de l'API ne pourront plus utiliser l'API.  

[HttpGet]

[Route ("GetOrders")]

 public IActionResult GetOrders (int customerId, int orderId)

 {

   var result = _orderService.GetOrdersForCustomer

                 (customerId, orderId);

   return Ok (résultat);

 }

Et c'est exactement comme ça que vous pouvez briser la compatibilité de votre API! La section qui suit présente les meilleures pratiques qui peuvent être adoptées pour rendre votre API rétrocompatible.

Conseils de compatibilité API

Maintenant que nous savons quel est le problème, comment concevoir nos API de la manière recommandée? Comment pouvons-nous nous assurer que notre API RESTful est rétrocompatible? Cette section répertorie certaines des meilleures pratiques qui peuvent être suivies à cet égard. 

Assurez-vous que les tests unitaires réussissent

Vous devriez avoir des tests écrits qui vérifieront si la fonctionnalité est intacte avec une nouvelle version de l'API. Les tests doivent être écrits de manière à échouer en cas de problème de compatibilité descendante. Idéalement, vous devriez avoir une suite de tests pour les tests d'API qui échouera et alerte en cas de problèmes de compatibilité descendante de l'API. Vous pouvez également avoir une suite de tests automatisés connectée au pipeline CI / CD qui vérifie la compatibilité descendante et alerte en cas de violation.

Ne modifiez jamais le comportement des codes de réponse HTTP

Vous ne devez jamais modifier le comportement des codes de réponse HTTP dans votre API. Si votre API renvoie 500 lorsqu'elle ne parvient pas à se connecter à la base de données, vous ne devez pas la changer en 200. De même, si vous renvoyez HTTP 404 lorsqu'une exception se produit et que vos clients utilisent cet objet et l'objet de réponse pour identifier ce qui s'est passé faux, changer cette méthode API pour renvoyer HTTP 200 rompra complètement la compatibilité descendante.

Ne modifiez jamais les paramètres

Évitez de créer une nouvelle version de l'API lorsque vous n'apportez que des modifications mineures, car cela pourrait être excessif. Une meilleure approche consiste à ajouter des paramètres à vos méthodes API pour incorporer le nouveau comportement. De la même manière, vous ne devez pas supprimer les paramètres d'une méthode API ou changer un paramètre de facultatif à obligatoire (ou vice-versa), car ces modifications casseront l'API et les anciens clients ou consommateurs de l'API ne pourront plus pour travailler avec l'API.

Version de votre API

La gestion des versions des API est une bonne pratique. La gestion des versions permet de rendre votre API plus flexible et adaptable aux changements tout en conservant la fonctionnalité intacte. Il vous aide également à mieux gérer les modifications du code et à revenir plus facilement à l'ancien code si le nouveau code pose des problèmes. Vous devez avoir une version différente de votre API RESTful avec chaque version majeure.

Bien que REST ne fournisse aucune indication spécifique sur la gestion des versions d'API, vous pouvez versionner votre API de trois manières différentes: en spécifiant les informations de version dans l'URI, en stockant les informations de version dans l'en-tête de demande personnalisé et en ajoutant les informations de version à HTTP Accept entête. Bien que la gestion des versions puisse vous aider à maintenir votre API, vous devez éviter d'essayer de maintenir de nombreuses versions de l'API pour marquer les versions fréquentes. Cela deviendra rapidement encombrant et contre-productif. 

Autres bonnes pratiques API

Vous ne devez jamais changer l'URL racine d'une API ou modifier les paramètres de chaîne de requête existants. Toute information supplémentaire doit être ajoutée en tant que paramètre facultatif à une méthode API. Vous devez également vous assurer que les éléments facultatifs ou obligatoires qui sont passés à une API ou qui sont renvoyés par une API ne sont jamais supprimés.

Les modifications apportées à une API RESTful sont inévitables. Cependant, à moins que vous ne respectiez les meilleures pratiques et que vous vous assuriez que l'API est rétrocompatible, vos modifications peuvent rompre la compatibilité de l'API avec les clients existants. Une API en production et utilisée par plusieurs clients doit toujours être rétrocompatible entre les versions.