Introduction

Depuis l’émergence des API web dans les années 2000 et leur popularisation un peu plus récente, le monde des développeurs informatique est tombé d’accord sur un certain nombre de règles à respecter, de bonnes pratiques à ne pas laisser de côté pour concevoir une bonne API.

Qu’est-ce qu’une bonne API ?

J’ai pu lire sur internet cette définition originale : « The API is like an artist performing on stage, and its users are the audience. ». Par cette métaphore, l’auteur veut simplement nous expliquer que l’API doit donner envie d’être utilisée. Une bonne API doit être conçue pour ses utilisateurs, elle doit être intuitive, facile à comprendre et à utiliser.

Quelques définitions

• API (Application Programming Interface) : un ensemble normalisé de classes, de méthodes ou de fonctions qui sert de façade par laquelle un logiciel offre des services à d’autres logiciels
• REST (REpresentational State Transfer) : style d’architecture logicielle définissant un ensemble de contraintes à utiliser pour créer des services web
• Resource : représentation de données qui peut-être associée à un certain nombre d’autres données et de méthodes (exemple : client)
• Collection : liste de resources (exemple : clients)
• URL (Uniform Resource Locator) : identifiant permettant de localiser une resource

Exemples concrets :

GET http://api.easyteam.fr/v1/employees

Dans ce premier exemple, n’importe quel utilisateur, informaticien de formation, comprend facilement que, d’une part, nous utilisons la version 1 de l’API d’Easyteam, et que nous cherchons à récupérer la liste des salariés.

GET http://api.easyteam.fr/v1/employees/243/addresses/2

Dans ce second exemple, l’utilisateur comprend que nous souhaitons afficher l’adresse secondaire associée au salarié donc l’identifiant est « 243 ».

DELETE http://api.easyteam.fr/v1/employees/243/addresses/2

Ici, nous demandons à supprimer cette adresse.

Nous venons de découvrir grâce à ces exemples la notion de ressources et de sous-ressources. Les sous-ressources sont des données liées aux ressources parentes, cela permet une navigation simple et compréhensible dans l’API.

 

Bonnes pratiques

Il existe donc un certain nombre de bonnes pratiques qui ressortent de l’ensemble de la communauté des architectes d’API. Voici les principales.

Pas de verbe dans l’URL, uniquement des noms

Le même auteur que la citation précédente a écrit : « The URL is a sentence, where resources are nouns and HTTP methods are verbs. ».

Comme nous l’avons vu dans les exemples en première partie, les actions (CRUD) que l’on souhaite réaliser sur les ressources doivent être communiquées grâce aux méthodes de requêtes HTTP.

Rappel des méthodes de requêtes HTTP :

• GET : La méthode GET demande une représentation de la ressource spécifiée
• POST : La méthode POST est utilisée pour envoyer une entité vers la ressource indiquée
• PUT : La méthode PUT remplace toutes les représentations actuelles de la ressource visée par le contenu de la requête
• PATCH : La méthode PATCH est utilisée pour appliquer des modifications partielles à une ressource
• DELETE : La méthode DELETE supprime la ressource indiquée

En utilisant correctement ces méthodes de requêtes HTTP, mettre un verbe d’action dans l’URL n’est pas nécessaire et serait même redondant.

Des noms au pluriel

Il est facile d’imaginer un cas d’utilisation où le résultat souhaité est une liste d’éléments et un autre où le résultat attendu est un élément unique et précis. Pour gérer ces deux cas d’utilisation, il est préférable de mettre les noms des ressources dans l’URL au pluriel plutôt qu’au singulier.

Explication par l’exemple :

Je veux récupérer la liste de tous les employés :

GET http://api.easyteam.fr/v1/employees

Je veux récupérer l’employé n°3 :

GET http://api.easyteam.fr/v1/employees/3

La première règle, dite dans l’introduction, est qu’il faut concevoir son API pour ses utilisateurs. Les utilisateurs sont des êtres humains, et il est naturel pour un être humain de comprendre que le pluriel renvoie une liste d’éléments, alors on utilise le pluriel. Et pour faciliter la navigation dans l’API, on ne mélange pas le pluriel et le singulier, le fait de rajouter l’identifiant « 3 » à la suite de l’URL fait comprendre facilement que l’on souhaite récupérer un élément unique et précis de la liste précédente.

Utiliser le bon code de retour HTTP

Chaque requête obtient (généralement) une réponse. La requête peut s’être bien passée comme elle peut avoir échouée. Dans les deux cas, les raisons peuvent être diverses et variées. Le protocole HTTP, sur lequel est basé le style d’architecture REST, prévoit une liste de codes à utiliser dans les réponses.

Voir la liste ici : https://fr.wikipedia.org/wiki/Liste_des_codes_HTTP

Cette liste, il faut l’utiliser au maximum.

Imaginez que vous posiez une question à quelqu’un et qu’il ne vous réponde pas… agaçant non ? Vous préféreriez qu’il vous dise qu’il ne peut pas vous répondre, cela vous fait déjà une information. Et même plus, vous aimeriez bien qu’il vous explique pourquoi il ne peut pas vous répondre.

Le principe est le même quand vous « discutez » avec une API. Plutôt qu’elle ne vous réponde pas du tout ou qu’elle vous dise : « ERREUR », vous préféreriez qu’elle vous indique : « 404 : la ressource que vous m’avez demandé n’existe pas ». Ainsi, vous saurez ce qu’il s’est passé et ne reposerez pas la même question automatiquement car vous savez qu’elle ne donne aucune réponse.

Versionner votre API

GET http://api.easyteam.fr/v1/employees

Vous n’arrêterez pas de faire évoluer votre API une fois qu’elle aura été publiée pour la première fois au public. Pour prévenir des éventuels problèmes de compatibilité avec les clients de votre API, vous devez prévoir un numéro de version. Tant que la compatibilité sera assurée, vous ne toucherez pas au numéro de version, mais dès lors qu’une mise à jour aura un impact sur l’interprétation des réponses par vos clients, vous serez obligés d’incrémenter ce numéro de version pour ne pas causer de dysfonctionnement chez les utilisateurs de votre API.

GET http://api.easyteam.fr/v2/employees

Informez vos clients de la mise à disposition d’une nouvelle version de l’API qu’ils consomment et ils pourront alors prévoir les évolutions de leur côté pour migrer en toute sérénité.

 

Autres notions (en vrac)

• Utilisez les entêtes HTTP Content-Type et Accept pour préciser le format (XML ou JSON) des messages que vous envoyez ou préféreriez recevoir
• HATEOAS (Hypermedia As The Engine Of Application State) : facilitez la navigation dans votre API. Consiste à ajouter des liens de navigation en complément dans les réponses.
• Trier, filtrer, paginer les données : utilisez les paramètres de requêtes (?category=manager)
• Sécurité : utilisez, par exemple, OAuth 2.0 pour sécuriser les données exposées par votre API
• …

Les bonnes pratique sont nombreuses, certaines présentées ici ont fait l’unanimité du fait de leur simplicité de compréhension. Rien n’est obligatoire, libre à vous de concevoir votre API comme bon vous semble, mais si vous souhaitez qu’elle soit utilisée, alors vous avez tout intérêt à suivre certaines règles adoptées par tous, qui feront que les utilisateurs comprendront facilement votre API et seront tentés de l’utiliser. KISS !