← API REST : concevoir, mûrir, documenter

HTTP, client-serveur, ressources : les fondations

≈ 20 minutes · Jalon M1

Le gain du jour : comprendre ce qu’est réellement une API REST — pas une technologie, mais un style architectural bâti sur HTTP — et savoir repérer une « ressource » dans n’importe quel problème.

API, késako ?

Une API (Application Programming Interface) est un contrat : une façon pour deux programmes de se parler sans se connaître intimement. Une API web expose ce contrat par-dessus le protocole HTTP, celui-là même que ton navigateur utilise pour charger des pages. Une API REST (REpresentational State Transfer) est un style particulier d’API web, décrit en 2000 par Roy Fielding dans sa thèse de doctorat — ce n’est ni un protocole, ni une norme, mais un ensemble de contraintes architecturales.

REST n’est pas un format

JSON, XML, HTML : REST ne dicte aucun format d’échange. On associe REST à JSON par habitude (c’est le format le plus léger et le plus lu par tous les langages), mais rien n’empêche une API REST de parler XML.

Le modèle client-serveur

HTTP repose sur une relation asymétrique :

Rôle	Ce qu’il fait
Client	Envoie une requête (request) : « je veux X »
Serveur	Renvoie une réponse (response) : le résultat, ou une erreur

Le client ignore comment le serveur est construit (base de données, langage, machine) ; le serveur ignore qui est le client (navigateur, app mobile, script Python). Cette séparation est la première contrainte REST : client et serveur évoluent indépendamment, tant que le contrat (l’API) ne change pas.

Deuxième contrainte essentielle : sans état (stateless). Chaque requête HTTP doit contenir toutes les informations nécessaires à son traitement — le serveur ne garde aucune mémoire d’une requête à l’autre. Pas de session côté serveur qui se souvient « où en est » ce client précis. Si une information doit persister (un utilisateur connecté), elle voyage dans chaque requête, généralement sous forme d’un jeton (on y reviendra dans la leçon sur l’authentification).

Pourquoi « sans état » change tout

Une API stateless peut être dupliquée sur 50 serveurs derrière un load-balancer sans coordination entre eux : n’importe quelle instance peut répondre à n’importe quelle requête, puisqu’aucune ne garde de mémoire du client. C’est ce qui rend REST si facile à faire passer à l’échelle.

Tout est une ressource

L’idée centrale de REST : le serveur n’expose pas des actions, il expose des ressources — des noms, pas des verbes. Une ressource est n’importe quelle chose qu’on peut nommer et manipuler : un utilisateur, une commande, une liste de commandes, un article de blog.

Chaque ressource a une URI unique qui l’identifie :

/users              → la collection de tous les utilisateurs
/users/42            → l'utilisateur d'identifiant 42
/users/42/orders      → les commandes de l'utilisateur 42
/users/42/orders/7     → la commande 7 de l'utilisateur 42

Remarque ce qui n’apparaît jamais dans une URI bien conçue : un verbe. Pas de /getUser?id=42 ni de /deleteOrder. L’URI dit quoi, pas comment ni quelle action. C’est le verbe HTTP (GET, POST, DELETE…) qui porte l’action — sujet de la prochaine leçon.

Repérer une ressource

Face à une fonctionnalité, pose-toi la question : « si je devais nommer cette chose comme un nom commun, ce serait quoi ? » « Envoyer un email » n’est pas une ressource, mais « un email » (/emails) en est une — envoyer un email devient alors créer une ressource email (POST /emails).

Requête et réponse : anatomie

Une requête HTTP a toujours la même forme :

GET /users/42 HTTP/1.1
Host: api.exemple.com
Accept: application/json
Authorization: Bearer eyJhbGciOi...

Ligne de requête : verbe (GET), chemin (/users/42), version HTTP.
En-têtes (headers) : métadonnées — format attendu, authentification, etc.
Corps (body) : optionnel, absent en général pour un GET.

Et la réponse qui correspond :

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 42, "name": "Alice", "email": "alice@exemple.com"}

Ligne de statut : code numérique (200) + texte (OK).
En-têtes : format du corps, cache, etc.
Corps : la représentation de la ressource — ici, du JSON.

Le mot représentation dans REST prend tout son sens ici : le serveur n’envoie pas « l’utilisateur 42 » (un enregistrement en base de données), il envoie une représentation de cet utilisateur à un instant T, dans un format donné (JSON). Le client, lui, transfère l’état de cette représentation (Representational State Transfer) — d’où le nom REST.

Vérifie ta compréhension

1. Dans une API bien conçue, où doit vivre un verbe d'action comme « supprimer » ?

2. Que signifie « stateless » (sans état) pour une API REST ?

3. Laquelle de ces URI respecte le style REST ?

À toi de jouer

Ouvre les outils de développement de ton navigateur (onglet Réseau/Network), va sur un site que tu utilises tous les jours, et trouve une requête GET vers une API (souvent au format JSON). Repère l’URI : est-elle « en noms » (RESTful) ou « en verbes » ?
Pour trois fonctionnalités d’une appli fictive de covoiturage (« proposer un trajet », « réserver une place », « annuler une réservation »), écris la ressource et le couple verbe HTTP + URI correspondants. Exemple : proposer un trajet → POST /trips.

Pour aller plus loin

📖 Source principale : Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures, chapitre 5 — « Representational State Transfer (REST) », le texte fondateur de REST (en anglais, mais le chapitre 5 se lit en 30 minutes).

🗂 Fiche de référence associée : Verbes, codes, en-têtes — antisèche.