Comment bien concevoir ses API

Qu'est-ce qu'une API ?

Il existe différents protocoles : 

• SOAP : Prend en charge un large éventail de protocoles de communication utilisés sur Internet, tels que HTTP, SMTP et TCP. Bien qu'il soit très répandu, il devient petit à petit obsolète,
• RPC : Le protocole RPC (remote procedural call) envoie plusieurs paramètres et reçoit des résultats. Il est le moins utilisé parmi ces protocoles, 
• WebSocket : Permet d'échanger des données entre un navigateur et un serveur par le biais d'une connexion persistante. Il peut être dangereux pour les utilisateurs si il est utilisés à des fins de récupérations de données,
• REST - repose sur une approche client/serveur qui sépare les parties avant et arrière de l'API et offre une flexibilité considérable en matière de développement et de mise en œuvre.

La plupart de nos développements utilisent ou créent des API REST.

Il permet de communiquer entre différentes interfaces ou services pour permettre à nos clients et aux utilisateurs de pouvoir envoyer et recevoir des données. 

Notre enjeux est de réaliser des flux de données les plus légers possibles, avec les informations nécessaires seulement.  

La méthode standard de communication entre les systèmes passe par les API.

Il est donc essentiel de créer des API REST correctement afin d'éviter tout problème à l'avenir.

Une API bien définie doit être facile à utiliser, concise et difficile à utiliser à mauvais escient.

Les 4 méthodes généralement utilisées

Un point important à prendre en compte est que nous utilisons généralement 4 méthodes HTTP :

• GET,
• POST,
• PATCH,
• DELETE.

Il est donc inutile d'avoir un appel getAllBooks et setAllBooks, nous pourrons le gérer via l'appel de méthode HTTP.

Nos conseils pour créer et maintenir une API performantes

1. Codes d'état propres à l'utilisateur

Il existe de nombreux codes d'état HTTP, mais nous n'en utilisons généralement que quelques-uns.

N'en utilisez pas trop, mais utilisez les mêmes codes d'état pour les mêmes résultats dans l'API, par exemple,

• 200 pour un succès général.
• 201 pour une création réussie (POST).
• 202 pour une demande réussie.
• 204 pour l'absence de contenu.
• 30X pour un contenu redirigé.
• 400 pour les mauvaises demandes.
• 401 pour les demandes non autorisées.
• 403 pour les permissions manquantes.
• 404 pour manque de ressources.
• 5xx pour les erreurs internes.

2. Utiliser des noms simples plutôt que des phrases 

Les phrases ne doivent pas être utilisés dans les chemins d'accès.

Au lieu de cela, le chemin doit contenir les noms qui identifient l'objet auquel le point de terminaison auquel nous accédons ou que nous modifions appartient.

Par exemple, au lieu d'utiliser /getAllBooks pour récupérer tous les livres, utilisez /books.

3. Utiliser des noms de ressources au pluriel

Utilisez le pluriel pour les noms de ressources, car cela convient à tous les types de points d'accès.

Par exemple, au lieu d'utiliser /book/:id/, utilisez /books/:id/.

4. Être cohérent

Lorsque nous disons qu'il faut être cohérent, cela signifie qu'il faut être prévisible.

Lorsqu'un point de terminaison est défini, les autres doivent se comporter de la même manière. Ainsi, utilisez le même cas pour les ressources, les mêmes méthodes d'authentification pour tous les points de terminaison, les mêmes en-têtes, les mêmes codes d'état, ...

5. Rester simple

Nous devrions faire en sorte que la dénomination de tous les points de terminaison soit orientée vers les ressources, comme elles le sont.

Si nous voulons définir une API pour les livres, nous la décrirons comme suit :

/books

/books/111

Ainsi, la première API récupère tous les livres, et la seconde un livre spécifique.

6. Traiter correctement les erreurs

Il s'agit ici d'éliminer toute confusion lorsqu'une erreur se produit.

Nous devons gérer les erreurs correctement et renvoyer un code de réponse indiquant ce qui s'est passé (des erreurs 400 à 5xx).

Nous devons renvoyer certains détails dans le corps de la réponse en même temps qu'un code d'état et non pas marquer "ERROR" par exemple.

8. Sécurité ! Sécurité ! Sécurité !

Un flux doit être sécurisé, c'est à dire :

1/ Nous voulons que toutes les communications entre un client et un serveur soient protégées, ce qui signifie que nous devons toujours utiliser SSL/TLS, sans aucune exception.

2/ Il faut également autoriser l'authentification par des clés API, qui doivent être transmises à l'aide d'un en-tête HTTP personnalisé avec une date d'expiration.

9. Utiliser la pagination

Il se peut qu'avec le temps vos flux deviennent gros, pensez dès le départ à mettre en place une pagination.

Nous recommandons d'utilisez page et limit pour le numéro de la page et le nombre de résultats dans celle-ci

Par exemple, /books?page=10&limit=20

10. La DOC !

Un projet ne peut pas être maintenable sans documentation à jour. 

Pour finir 

Il existe mille et une façon de développer des API.

De notre côté, lorsque nous en avons la possibilité, nous partons sur une stack Symfony avec API Platform ce qui nous permet d'avoir des projets propres, optimisés et maintenable. 

Si vous voulez aller plus loin, nous vous conseillons de consulter les spécifications Swagger et d'utiliser des outils puissants comme Postman ou encore Insomnia.

(source image : https://www.pexels.com/photo/programmer-holding-a-paper-cutout-with-an-api-quote-11035364/)