API Rest : comment ça fonctionne et pourquoi l’utiliser ?

Les API REST sont au cœur du fonctionnement dune majorité des outils numériques développés et utilisés aujourdhui. Dans un environnement classique de communication front-end → backend, mais aussi dans une architecture micro-services, l'API REST reste un moyen de communication privilégié.

L'API Rest est aussi l'un des meilleurs moyens pour vous permettre d'exposer certaines de vos données et d’inviter à la collaboration entre tiers.

Aujourd'hui, maitriser les tenants et aboutissants de REST est primordial, pour les profils techniques, mais aussi pour des profils plus fonctionnels, dans un contexte où l'API elle-même est un produit.

Prenons le temps de revenir ensemble sur, ce qu'est une API REST, concrètement.

C'est quoi une API REST ?

Une API (Application Programming Interface) est une interface de programmation permettant d’accéder à un ou plusieurs services comme des données ou des fonctionnalités fournies par un système tiers. Elle se base sur une architecture client-serveur.

Dans le schéma suivant, nous prenons l’exemple de l’application Uber (permettant de commander une course) qui fait appel à l’API de Google Maps pour avoir accès à l’itinéraire d’un client et une API de paiement pour facturer le trajet.

Schéma d’explication du fonctionnement de l’application Uber avec API Source : Hubvisory Source

Rest (Representational State Transfer) est une architecture logicielle basée sur le HTTP (protocole de référence qui définit les communications sur le web), qui définit un ensemble de lignes directives architecturales à utiliser pour la création d'applications web. Les six principes REST qui guident la conception des API sont les suivants :

1. Découplage client-serveur

Ce principe est basé sur le fait que le client (entité qui effectue la demande des ressources) et le serveur (entité qui contient les ressources) doivent être développés de manière indépendante. Ainsi donc, en séparant les préoccupations liées à l’interface utilisateur de celles liées au stockage des données, vous améliorez la portabilité sur différentes plateformes et augmentez l’evolutivité en simplifiant les composants serveurs.

Avantage : le client peut évoluer d’une version à l’autre sans perturber le serveur et vice-versa.

2. Interface uniforme

Ce principe stipule que tout type d’appareil client devrait interagir de manière uniforme avec le serveur. Il y a quatre éléments clés à respecter pour cette contrainte:

• L’identification des ressources par un URI (Uniform Ressource Identifier)
• La manipulation des ressources via des représentations. Quand le client envoie une demande via l’URI, il obtient une réponse (souvent en JSON) qui est la représentation de la ressource
• Les messages doivent être auto-descriptifs pour chaque demande
• Le principe HATEOAS ( Hypertext As The Engine Of Application State) qui utilise des liens hypertext dans les réponses envoyées par le serveur pour permettre au client de savoir où partir chercher plus d’informations concernant la ressource

{ “products”: [ { “product-ID” : 38937, “links”:{ “rel”:”self”, “href”:”/products/38937″ } } ]}

Avantage : favorise la généralité, car tous les composants interagissent de la même manière

3. Sans état (stateless)

Ce principe stipule que le serveur ne doit pas stocker des informations relative au client(à l’exception de celles concernant l’authentification si nécessaire). Par conséquent, toutes requêtes effectuées par le client doit contenir toutes les données nécessaires pour les traiter.

Avantage : offre la possibilité de paralléliser les requêtes

4. Mise en cache

Ce principe stipule que la réponse envoyée par le serveur doit indiquer si elle est cacheable ou non et pendant combien de temps les réponses peuvent être mises en cache côté client. Si la réponse est cacheable, le client pourra récupérer cette réponse dans son propre système et il n’aura plus besoin d’envoyer de requêtes supplémentaires au serveur pour obtenir les mêmes données, ce qui améliore réellement l’optimisation de votre réseau pour les requêtes ultérieures.

Avantage : réduit la latence du réseau

5. Architecture système en couches

Ce principe indique que l’architecture doit être composée de plusieurs couches qui n’interagissent respectivement qu’avec celles voisines.

Avantage : Sécurité et stabilité de l’application car les composants de chaque couche ont des interactions limitées.

_Schéma d’explication des interactions entre couches voisines_Source : Hubvisory Source

6. Code à la demande (facultatif)

Ce principe stipule qu’en plus des données, le serveur peut fournir également du code exécutable, comme par exemple du javascript, et le client peut télécharger ce code et l‘exécuter.

Avantage : diminue le nombre de fonctionnalités essentielles à pré-implémenter.

Comment fonctionne une API Rest ?

Le client envoie une requête HTTP en précisant la ressource, le serveur traite la requête en récupérant les informations demandées dans sa base de données et ensuite renvoie une représentation de la ressource.

_Schéma d’explication du fonctionnement API avec requêtes HTTP_Source : Hubvisory Source

Requête

Une requête API Rest est généralement composée de :

1. Point de terminaison

Il contient une URI permettant au serveur de pouvoir identifier la ressource

2. Une méthode HTTP

Elle décrit le type de requête que le client envoie au serveur. On y retrouve les méthodes suivantes :

• GET récupère la représentation de la ressource
• POST créée de nouvelles données
• PUT modifie entièrement une ressource
• PATCH modifie partiellement une ressource
• DELETE supprime des données
• OPTIONS récupère les opérations REST disponibles3.Header

Les entêtes permettent de communiquer des informations utiles au client et au serveur, par exemple des données d’authentification.

4. Body

Le body permet de fournir des données complémentaires pour le traitement de la requête. Par exemple, des champs à modifier avec la méthode PATCH.

Réponse

L’API Rest répond aux différentes requêtes avec des codes réponses HTTP. Les plus courants sont les suivants :

• 200 Ok : la demande a été acceptée et bien traitée. La ressource se trouve dans le corps de la réponse.
• 201 Created : ressource créée avec succès. Ce code réponse est lié aux opérations de POST ou de PUT.
• 400 Bad request : les informations renseignées dans la requête sont soit erronées soit vides, par conséquent la demande n’est pas valide.
• 401 Unauthorized : l’utilisateur n’a pas les droits nécessaires pour accéder à la ressource demandée
• 404 Not Found : la ressource indiquée est soit incorrecte, soit elle n’existe pas.
• 500 Internal Server Error : problème lié au serveur ou à la demande.

Voici la liste complète si vous êtes curieux.

Une API REST est donc une interface de programmation d’application qui respecte les lignes directives de l’architecture logicielle Rest.

Il est important de noter qu'au delà de REST, il existe d'autres moyens de définir des services web.

Alternatives à REST

API GraphQL

GraphQL est un langage de requête, de manipulation de données pour les API et d’exécution côté serveur qui fournit au client uniquement les données demandées.

Contrairement à REST, une API GraphQL ne repose pas sur la création de plusieurs points de terminaison (endpoints).

Un serveur GraphQL expose un endpoint de méthode POST que le client pourra appeler en formulant une requête GraphQL dans le corps de la requête HTTP.

Cette requête, pour fonctionner, doit correspondre à un resolver mis à disposition par le serveur.

//requête Resthttps://api.com/products

Puis :

//requête GraphQLquery getProducts { products { id title description } }

L'API GraphQL est privilégiée lorsque notre service web est consommé par un grand nombre de services différents. Ainsi, chaque service peut fonctionner en consommant uniquement la donnée dont il a besoin, et on limite les risques d'une architecture REST des ressources inadaptée à une certaine typologie de consommateurs d'API.

2. API SOAP (Simple Object Access Protocol)

SOAP est un protocole de messagerie qui peut être construit en utilisant la technologie Microsoft appelée WCF (Windows Communication Foundation), contrairement à REST, le SOAP ne renvoie que du XML et les services web ne sont rien d'autres que vos services SOAP.

SOAP permet au client d’obtenir des réponses indépendamment des plateformes et des langages.

Différence avec Rest :

• L’API Rest renvoie du JSON, XML ou du YAML tandis que l’API SOAP ne renvoie que du XML
• L’API REST est un style architectural et SOAP est un protocole
• Les API Rest sont légères contrairement aux services web SOAP
• Les requêtes SOAP sont sous format XML

<!-- requête SOAP --><?xml version="1.0"?><soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"><soap:Header></soap:Header><soap:Body><m:GetUser><m:UserId>123</m:UserId></m:GetUser></soap:Body></soap:Envelope>

Pourquoi a-t-on besoin d'une API Rest ?

L'utilisation d'APIs s'est démocratisée dans le domaine du développement web, son utilité principale étant d'offrir une modularité aux projets, grâce au découplage client serveur.

Il existe de nombreux format d'APIs (cf ci-dessus) mais REST continue à faire partie des formats les plus employés, et l'expression "RESTful" fait aujourd'hui partie du vocabulaire courant d'un Développeur.

Bien entendu, REST, n'est pas l'ultime solution dans le domaine du développement web et d'autres formats sont apparus pour résoudre les problématiques auxquelles REST n'était pas capable de répondre (tel que GraphQL); mais sa simplicité, sa robustesse et sa démocratisation en font un élément incontournable dans la création d'un produit numérique, que chaque Développeur, mais aussi chaque Product Owner, se doit de connaître.