REST API Design — Les best practices

L’échange et l’exposition des données d’une entreprise est une pratique en plein essor dans les systèmes d’informations, via la mise en place d’API, mais aussi et surtout dans des entreprises traditionnelles plus éloignées de ce domaine.

En effet, la mise en place des 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. Néanmoins, il existe quelques bonnes pratiques à suivre :

• Une API doit être facile à comprendre et simple d’utilisation : on dit souvent qu’une API est comme un 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, que Neoxia se propose de vous partager dans une série d’articles qui s’appuient sur nos expériences et nos missions de ces dernières années.

I — Versioning

Le versioning est le moyen de communiquer aux consommateurs 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.

Nos précédentes missions et notre expérience nous ont permis de nous construire quelques convictions au sujet du versioning des APIs.

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.

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.

Ainsi, il existe différentes façons de procéder pour établir la version d’une API :

Voici quelques avantages et inconvénients de chaque méthode :

On privilégie et préconise l’approche de Google dans la gestion des versions des APIs car elle correspond à notre idée des APIs : faciles à comprendre.

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

[HTTP VERB] /<domain>/v1/<resource>/{id}

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 Header 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)

II — Les 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.

Une autre tâche d’importance est de découper correctement les ressources afin de permettre un niveau de granularité adapté à votre métier.

Faites de vos ressources des noms

Mettons-nous dans la peau d’un producteur de fruits bio qui souhaite diffuser des informations sur son activité à travers une API.

Nous conseillons d’utiliser des noms pour nommer nos ressources de la façon suivante (en français pour illustrer):

• GET /v1/fruits — une collection de fruits
• GET /v1/fruits/{fruitsId}?disponible=true
• GET /v1/fruits/{fruitsId}?type=2
• POST /v1/fruits

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 :

• /v1/getAllFruits— une collection de fruits
• /v1/getFruitDisponible
• /v1/getFruitTypePomme
• /v1/getFruitTypePommeGala
• /v1/getFruitTypePommeGalaDisponible
• /v1/newPomme

La bonne granularité et le bon découpage

Nous recommandons toutefois de concevoir votre API avec le niveau de granularité 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.

Pour reprendre l’exemple de notre producteur de fruits bio, la question qui se pose dans le découpage est de savoir quel sera le bon niveau de granularité à adopter et comment les ressources seront consommées par les utilisateurs.

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 (cf. article 1).

Pour résumer, les bonnes pratiques que nous mettons en place dans nos projets sont les suivantes :

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

III — Les statuts

Comme évoqué dans la partie précédente, 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, On s’appuie et insiste 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.

Utilisez des verbes HTTP pour vos ressources

Ainsi, pour effectuer des opérations sur les ressources, les API de type REST (REpresentational State Transfet) utilisent le standard HTTP, en l’occurrence les méthodes suivantes :

• 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 (cf. article 1)

Exemple :

HTTP status code

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.

Les codes sont divisés en catégories:

2xx Success

Cette classe de codes d’état indique que l’action demandée par le client a été reçue, comprise et acceptée.

3xx Redirection

Cette catégorie de code d’état indique que le client doit effectuer une action supplémentaire pour terminer la demande.

4xx Client Error

Cette classe de code d’état est destinée aux situations dans lesquelles l’erreur semble avoir été provoquée par le client.

5xx Server Error

Cette classe de code d’état indique les cas dans lesquels le serveur a rencontré une erreur et est incapable d’exécuter la demande.

Lors de la mise en place d’un projet d’API, On recommande a minima d’implémenter les codes de retour suivants :

Exemple :

Un acteur fait une requête pour récupérer un profil utilisateur par ID. Une implémentation possible serait que les utilisateurs qui n’existent pas renvoient une erreur 404, tandis que les utilisateurs qui existent mais ne sont pas accessibles renvoient une erreur 403.

GET /users/U124

404 Not Found

GET /users/U123

403 Forbidden

Un acteur malintentionné peut utiliser cette information pour déterminer quels IDs sont valides et lesquels ne sont pas assignés. Cette information peut ensuite servir pour lancer une attaque.

Une meilleure approche qu’on recommande serait que toutes les ressources non accessibles par l’utilisateur retournent une erreur 404.

Nous pouvons donc résumer certaines des bonnes pratiques qu’on recommande de la façon suivante :

• 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.

Conclusion

Quelques aspects des bonnes pratiques API ont été abordés dans cette article. Comme nous l’avons vu, il existe des bonnes pratiques à suivre pour réussir la mise en place de vos APIs, comme les standards HTTP ou le bon découpage des ressources.

Néanmoins, l’étendue de ces bonnes pratiques est vaste et dépend de cas d’usages spécifiques de chaque métier. Il n’y a pas d’approche unique qui convienne à toutes les entreprises. Les conseils et recommandations que nous avons évoqués plus haut doivent être adaptés à votre cas et votre 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é. KISS (Keep It Simple, Stupid).

Cette article a été co-écrit avec Alexandre BRUN

Dossier API Management par Neoxia

Retrouvez ici tous nos articles concernant les APIs.