API Management : 3 conseils pratiques pour optimiser sa démarche d’échange et d’exposition des données

L'échange et l’exposition des données d’une entreprise est une pratique en plein essor, via la mise en place d’API. Si chaque projet d'API management est unique et dépend des cas d'usages spécifiques à son métier, certaines bonnes pratiques méritent d'être partagées : stratégie de versioning, découpage des ressources et du choix des statuts.

La mise en place d’API crée un nouveau modèle d’interconnexion des entreprises entre elles ou en leur sein, basé sur l’accès sécurisé aux fonctionnalités de leurs SI respectifs et l’échange de données. Cette interconnexion facilite la création de nouveaux produits, de nouveaux services ou modèles commerciaux et de nouvelles expériences utilisateur. Il n’existe aujourd’hui pas de consensus sur la meilleure façon de prototyper / concevoir une API que l’on souhaite exposer, car chaque projet est unique et dépend des cas d’usage spécifiques à chaque métier. En préambule, il est important d’avoir en tête les postulats suivants :

Une API doit être facile à comprendre et simple d’utilisation. On dit souvent qu’une API est comme une bonne blague : si on a besoin de l’expliquer, c’est qu’elle est ratée.
Il doit être difficile d’en faire une mauvaise utilisation : l’utilisation d’une API ne doit pas pouvoir être détournée de son usage premier.
Elle doit être complète mais évolutive.

Une fois que l’on a décidé d’exposer des services utilisables par des tiers, la démarche s’accompagne de certaines bonnes pratiques au niveau de la stratégie de versioning, du bon découpage des ressources et du choix des statuts.

Penser sa stratégie de versioning

Le versioning est le moyen de communiquer aux partenaires qu’une API a évolué et qu’un changement risque de casser l’existant. En effet, une API peut être vue comme un contrat qui forme la base de la communication, et définit les formats d’échanges entre le producteur et le consommateur. Si vous décidez, en tant qu’émetteur, de modifier un aspect du contrat, ce changement peut avoir un impact important pour les autres acteurs qui consomment votre API.

Une des bonnes pratiques à mettre en place est donc de définir quelle sera votre politique de mise à disposition des différentes versions de votre API. Ainsi, votre stratégie de versioning est essentielle au succès de votre projet et de ceux de vos partenaires : elle rassure les consommateurs de votre API et renvoie une image positive et sérieuse de votre démarche.

Ce qu’est le versioning ;

Le versioning est le moyen de communiquer quand un changement risque de casser l’existant
Le versioning doit avoir lieu lorsque de nouveaux champs obligatoires sont ajoutés aux requêtes, ou les données précédemment disponibles sont supprimées des données utiles.

Ce que le versioning n’est pas :

Ce n’est pas un indicateur de la version courante du code.
Les consommateurs n’ont pas besoin de connaitre la version du logiciel derrière votre API. Cette information ne va pas les aider à construire ou à maintenir leurs propres applications.

Ainsi, il existe différentes façons de procéder pour établir la version d’une API. L’approche de Google dans sa gestion des versions des APIs nous semble être la plus simple à comprendre.

Ainsi pour indiquer la version majeure d’une API, nous recommandons cette notation :

[VERBE HTTP] /<domain>/v1/<resource>/

Cette approche est simple et peut être facilement utilisée dans les outils de test. Elle est également non ambiguë, c’est-à-dire que lorsqu’un changement majeur intervient, l’URL change. Enfin, elle est intuitive, car nous pouvons voir que le domaine a mis à jour sa ressource.

Et pour un changement de version mineure, nous conseillons de transmettre cette information au travers du Entête HTTP : HTTP Header: api-version

Par extension, afin de conserver cohérence et lisibilité, il nous semble indispensable de :

Ne jamais exposer une API non versionnée
Utiliser principalement des versions majeures, limiter les versions mineures
Donner du temps à vos consommateurs avant de déprécier une version
Lorsqu’une nouvelle version est créée, déployer tous les proxies en même temps (évite la confusion en cas de croisement de version entre le code et l’API).
Si un client essaie d’appeler une API dépréciée, retourner systématiquement un code d’erreur HTTP 410 Gone
Synchroniser votre stratégie de version API et celle de vos branches (git)

La bonne granularité et le bon découpage des ressources

Lorsqu’une entreprise se lance dans un projet d’API Management, même si chaque projet dépend des cas d’usages spécifiques au métier, de nombreuses interrogations portent sur les ressources. Quelle que soit la taille de l’organisation ou son secteur d’activité, cette question fait partie des discussions stratégiques tout au long du cycle de vie du projet. Rapide tour de ce sujet central.

La cohérence des ressources que vous allez exposer est fondamentale à la réussite de votre API. En effet lorsque vous exposez une ressource, celle-ci contient des données métiers, des relations avec d’autres ressources pour permettre d’y accéder et de les manipuler.

Rappelez-vous qu’une API doit être facile à comprendre. La difficulté principale réside dans le fait de nommer correctement les objets que l’on souhaite exposer.

Nous conseillons d’utiliser des noms pour nommer nos ressources plutôt que d’utiliser des verbes qui complexifient la compréhension de l’objet métier et qui peut rallonger la liste d’URIs sans modèle consistant

Une autre tâche d’importance est de découper correctement les ressources afin de permettre un niveau de granularité adapté à votre métier et le plus fin possible : cela simplifie chaque service. Le principe clé est de concevoir des services pouvant être réutilisés et combinés de différentes manières.

Cela peut sembler simple sur le papier, néanmoins la définition d’un bon découpage s’avère complexe dans les faits. En effet, le besoin peut être mal exprimé ou la question mal posée, l’identité et le besoin des consommateurs peuvent être mal définis en amont, et cerise sur le gâteau, votre API peut évoluer avec le temps.

Pour résumer, 3 bonnes pratiques à retenir concernant les ressources :

Ne pas utiliser de verbes mais des noms dans vos URI ;
Concret est mieux qu’abstrait : il faut trouver le juste milieu
Déplacer la complexité dernière le “?” dans l’URL (filtres, pagination…etc…)

L’utilisation des standards HTTP pour gérer les statuts

Comme vu précédemment, le nommage des objets à exposer est important car celui-ci facilite la compréhension, la facilité d’utilisation et l’adoption de votre API. Pour effectuer des opérations sur ces noms, il nous semble opportun de miser sur l’utilisation des standards HTTP, même si chaque projet dépend des cas d’usages spécifiques à chaque métier. Ne réinventons pas la roue, et utilisons les ressources à notre disposition pour effectuer des actions sur ces objets métiers.

Ainsi, pour effectuer des opérations sur les ressources, les API de type REST 1 utilisent le standard HTTP, et misent sur des verbes : POST (création), GET (lecture et recherche), PUT (mise à jour), PATCH (mise à jour partielle), DELETE (suppression). Nous recommandons d’utiliser uniquement ces verbes pour effectuer des opérations sur les ressources, afin de faciliter la compréhension de ce que permet votre API.

Nous recommandons également l’utilisation d’un autre standard HTTP : les codes de retour.

Les codes d’état HTTP vont permettre de communiquer efficacement avec le consommateur de votre API, car ils ont une signification quant à ce que permet votre API (exemple : 2xx Success = l’action demandée par le client a été reçue, comprise et acceptée ; 3xx Redirection = le client doit effectuer une action supplémentaire pour terminer la demande, 4xx Client Error = erreur provoquée par le client, 5xx Server error = erreur provoquée par le serveur, etc.).

Il faut ainsi retenir que :

Les codes réponses doivent renseigner seulement ce que le développeur doit savoir sur votre API.
Toutes les ressources non accessibles par l’utilisateur doivent retourner un code 404 pour éviter de faire fuiter une information qui pourrait être utile lors d’une attaque contre votre API.

S’il existe de bonnes pratiques à suivre pour réussir la mise en place de vos APIs, comme les standards HTTP ou le bon découpage des ressources, leur étendue est vaste et dépend de cas d’usages spécifiques à chaque métier. Il n’existe pas d’approche unique qui convienne à toutes les entreprises : chaque conseil est à adapter à son besoin. Gardons à l’esprit qu’une API est un contrat passé avec un consommateur, et votre démarche doit être tournée vers ce dernier en gardant un état d’esprit orienté simplicité.

1 Le protocole REST (REpresentational State Transfer) constitue un style architectural et un mode de communication fréquemment utilisé dans le développement de services Web. Le recours à REST est souvent privilégié par rapport au style SOAP, plus lourd, car REST ne consomme pas autant de bande passante, ce qui rend son utilisation plus pratique sur Internet.