Concept : les bases d'une API REST (requête/réponse)

Qu'est-ce qu'une API ? L'analogie du restaurant

Avant de parler de REST, démystifions le terme API (Application Programming Interface). Imaginez que vous êtes dans un restaurant. Vous (le client) voulez commander un plat. Vous ne pouvez pas entrer dans la cuisine (le serveur) pour le préparer vous-même. Vous devez passer par un intermédiaire : le serveur.

Vous consultez un menu (la documentation de l'API) qui vous indique ce que vous pouvez commander. Vous passez votre commande au serveur (vous envoyez une requête). Le serveur transmet votre commande à la cuisine, qui la prépare. Enfin, le serveur vous apporte votre plat (il vous retourne une réponse).

Une API est ce serveur. C'est une interface bien définie qui permet à deux applications de communiquer entre elles en suivant un ensemble de règles, sans avoir à connaître les détails de leur fonctionnement interne. Vous n'avez pas besoin de savoir comment la cuisine est organisée, seulement comment passer une commande valide.

REST : Des règles du jeu pour une communication claire

REST (REpresentational State Transfer) n'est pas une technologie ou un langage, mais un style d'architecture. C'est un ensemble de contraintes et de principes pour concevoir des API. L'idée est de s'appuyer sur les standards du web qui existent déjà et qui ont fait leurs preuves, principalement le protocole HTTP.

En suivant les principes REST, les développeurs s'assurent que leurs API sont prévisibles, standardisées et faciles à utiliser. L'une des idées centrales de REST est de traiter toute information comme une ressource (un utilisateur, un produit, un article). Chaque ressource est identifiable par une URL unique, que l'on appelle un endpoint.

La Requête : Comment votre application formule sa demande

Chaque interaction commence par une requête HTTP envoyée par votre application (le client) vers le serveur de l'API. Une requête est composée de plusieurs parties :

• Le Verbe HTTP (ou méthode) : Il indique l'action que vous souhaitez effectuer sur la ressource. Les quatre verbes les plus courants correspondent aux opérations CRUD (Create, Read, Update, Delete).
  • GET : Pour lire une ressource (ex: récupérer les informations d'un utilisateur).
  • POST : Pour créer une nouvelle ressource (ex: ajouter un nouvel utilisateur).
  • PUT / PATCH : Pour mettre à jour une ressource existante.
  • DELETE : Pour supprimer une ressource.
• L'Endpoint (URL) : L'adresse unique qui identifie la ressource. Par exemple, https://api.exemple.com/users/123 cible l'utilisateur ayant l'ID 123.
• Les En-têtes (Headers) : Des métadonnées sur votre requête, comme le format des données que vous envoyez (ex: Content-Type: application/json) ou des informations d'authentification (une clé API).
• Le Corps (Body) : Utilisé principalement avec POST ou PUT, il contient les données que vous envoyez au serveur, le plus souvent au format JSON. Une requête GET n'a généralement pas de corps.

La Réponse : Comment le serveur communique le résultat

Après avoir traité votre requête, le serveur de l'API renvoie une réponse HTTP. Comme la requête, elle est structurée et contient des informations cruciales :

• Le Code de Statut : Un nombre à trois chiffres qui indique si la requête a réussi ou échoué. C'est la première chose que votre code doit vérifier.
  • 2xx (Succès) : 200 OK (la requête a réussi), 201 Created (la ressource a été créée).
  • 4xx (Erreur client) : 400 Bad Request (votre requête est mal formée), 401 Unauthorized (vous n'êtes pas authentifié), 404 Not Found (la ressource n'existe pas).
  • 5xx (Erreur serveur) : L'API a rencontré un problème de son côté.
• Les En-têtes (Headers) : Des métadonnées sur la réponse, comme le format des données retournées.
• Le Corps (Body) : C'est ici que se trouve la ressource que vous avez demandée, presque toujours au format JSON. C'est cette partie que vous allez parser pour l'utiliser dans votre application, exactement comme nous l'avons appris dans le chapitre précédent !

Un cycle complet : L'exemple d'une requête GET

Visualisons le dialogue complet pour récupérer des informations sur un livre via une API imaginaire.

1. Client (votre script Ruby) : "Je veux les informations sur le livre avec l'ID 789."
2. Construction de la requête :
   • Verbe : GET
   • Endpoint : https://api.librairie.com/books/789
3. Envoi : La requête est envoyée sur Internet vers les serveurs de l'API.
4. Serveur de l'API : Reçoit la requête, comprend qu'il doit chercher le livre 789, le trouve dans sa base de données.
5. Construction de la réponse :
   • Code de statut : 200 OK
   • Corps : {"id": 789, "title": "Devenir opérationnel en Ruby", "author": "Un auteur génial"}
6. Réception : Votre script Ruby reçoit la réponse, vérifie que le statut est 200, puis parse le corps JSON pour extraire le titre et l'auteur.

Ce cycle requête-réponse est le battement de coeur de la communication sur le web moderne. Dans la section suivante, nous utiliserons la gem HTTParty pour construire et envoyer ces requêtes de manière très simple.