Qu’est-ce qu’une REST API et comment fonctionne-t-elle ?

Une REST API est une API web qui applique les contraintes architecturales formalisées par Roy Fielding (2000) et utilise HTTP pour échanger des ressources. Elle standardise les échanges entre systèmes, améliore la scalabilité et rend possible le caching et la séparation client/serveur.

Quel problème REST a-t-il résolu ?

Je situe REST dans son but essentiel : permettre l’interopérabilité entre clients, backends et services tiers en réduisant la complexité des échanges entre systèmes hétérogènes.

Avant REST, de nombreuses architectures étaient des monolithes ou utilisaient des protocoles propriétaires. Ces approches posaient plusieurs problèmes concrets :

• Couplage fort entre interface et logique métier : Une modification d’un client pouvait imposer une refonte du backend.
• Gestion d’état côté serveur : Les sessions serveur empêchaient la montée en charge horizontale facile.
• Formats et protocoles incompatibles : XML propriétaire, RPC spécifiques, ou middleware exigeant des adaptateurs coûteux.

Je détaille pourquoi REST a réduit ces verrous. REST repose sur HTTP, des conventions simples (URI pour les ressources, verbes HTTP comme GET/POST/PUT/DELETE) et la statelessness (absence d’état serveur partagé entre requêtes). Ces principes facilitent l’intégration de services tiers (paiement, authentification, lutte contre la fraude) et diminuent le coût de maintenance.

Cas d’usage réel : Authentification token pour un service de paiement. Un client mobile obtient un jeton OAuth2 (ou un JWT) et appelle l’API paiement sans session serveur. L’en-tête standard Authorization transmet le jeton, ce qui rend l’intégration triviale pour un fournisseur tiers.

curl -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"amount":100,"currency":"EUR","card_id":"abc123"}' \
  https://api.exemple.com/payments

Exemples concrets de gains :

• Ajout d’un nouveau client mobile : Pas de refonte serveur si l’API expose des ressources cohérentes.
• Intégration d’un prestataire de fraude : Appels HTTP standard, format JSON, authentification token.
• Maintenabilité réduite : Moins d’adaptateurs propriétaires, diagnostics plus simples.

Critère	Monolithique	RESTful
Évolutivité	Difficile à scaler indépendamment	Facile à scaler par service/stateless
Couplage	Fort entre clients et serveur	Faible grâce à contrats HTTP/JSON
Réutilisabilité	Limitée, dépend du monolithe	Élevée, services réutilisables par tiers

Pour rappel, REST a été formalisé par Roy Fielding en 2000 et reste majoritaire dans l’industrie (voir rapports « State of the API » de Postman pour les tendances d’adoption).

Qu’est-ce qu’une REST API exactement ?

Je définis une REST API comme un contrat d’échange qui combine une interface uniforme (REST) et le protocole HTTP pour manipuler des ressources.

API signifie Application Programming Interface, c’est l’ensemble des méthodes, formats et conventions par lesquelles une application expose des fonctionnalités à d’autres programmes. REST signifie Representational State Transfer, un style architectural décrit formellement par Roy Fielding dans sa thèse de 2000. HTTP signifie HyperText Transfer Protocol, le protocole le plus courant utilisé pour transporter les requêtes et réponses entre clients (frontends, outils) et serveurs (backends).

Voici les points clés :

• Contrat versus implémentation : L’API est le contrat public (endpoints, verbes, schémas de données). L’implémentation est le code serveur qui respecte ce contrat et peut changer sans casser les clients si le contrat reste stable.
• REST comme ensemble de contraintes : Les contraintes principales sont Client-Server (séparation des responsabilités), Stateless (pas d’état serveur entre requêtes), Cacheable (réponses cacheables), Uniform Interface (identification des ressources par URI + méthodes standard), Layered System, et Code-On-Demand (optionnel).
• Méthodes HTTP et RFC : Les méthodes usuelles sont GET (lire), POST (créer), PUT/PATCH (mettre à jour), DELETE (supprimer). Le comportement attendu des méthodes est détaillé dans RFC 7231 (HTTP/1.1 Semantics and Content).
• Protocoles fréquemment utilisés : HTTP/1.1 reste courant, HTTP/2 apporte multiplexing et performance. Les clients modernes (navigateurs, mobiles) parlent surtout HTTP; les serveurs peuvent supporter les deux versions.
• Bénéfices immédiats : Standardisation des endpoints facilite la montée en charge et la maintenance. Facilité de test avec curl ou Postman. Compatibilité avec un écosystème riche d’outils (proxies, load balancers, observabilité).

Exemple concret (requête GET avec curl) :

curl -i -X GET "https://api.example.com/users/42" -H "Accept: application/json"

Outils et références utiles :

• Postman (client API graphique).
• curl (outil en ligne de commande).
• Roy Fielding, « Architectural Styles and the Design of Network-based Software Architectures », 2000.
• RFC 7231 (HTTP/1.1 Semantics and Content).

Quelles sont les six contraintes de REST ?

J’expose ici les six contraintes architecturales de REST et leur impact pratique, telles que définies par Roy Fielding (Fielding 2000).

Client-Server : Séparation claire entre client (interface utilisateur) et serveur (gestion des données) en une phrase.

• Objectif : Favoriser la modularité et la séparation des responsabilités pour faciliter l’évolution indépendante des deux côtés.
• Exemple : Un front-end React interrogeant une API Python isolée, permettant de redéployer l’UI sans toucher au back-end.
• Compromis : La latence réseau et la nécessité d’un contrat API strict (versioning) peuvent complexifier l’intégration.

Stateless : Chaque requête contient toutes les informations nécessaires pour être traitée, sans état stocké côté serveur.

• Objectif : Simplifier la scalabilité horizontale et le routage des requêtes entre serveurs.
• Exemple : Un load balancer peut diriger n’importe quelle requête vers n’importe quel nœud car aucune session serveur n’est requise.
• Compromis : Le client doit parfois renvoyer des jetons ou recréer du contexte, ce qui augmente la charge et la complexité côté client.

Cacheable : Les réponses doivent être identifiables comme cacheables ou non.

• Objectif : Améliorer la performance et réduire la charge en réutilisant des réponses mises en cache.
• Exemple : En-têtes HTTP Cache-Control (voir RFC 7234) permettent aux CDN et navigateurs de mettre en cache les réponses.
• Compromis : Une mauvaise configuration de cache peut servir des données obsolètes ou incohérentes.

Uniform Interface : Interface standardisée qui simplifie l’architecture par des conventions (URI, méthodes HTTP, représentations).

• Objectif : Réduire la complexité client en imposant des règles communes (GET pour lire, POST pour créer, etc.).
• Exemple : Utiliser /articles pour une collection et /articles/{id} pour une ressource individuelle.
• Compromis : Trop de rigidité dans l’interface peut empêcher des optimisations spécifiques au domaine.

Layered System : Architecture en couches intermédiaires (proxy, gateway, cache) entre client et serveur.

• Objectif : Autoriser des composants intermédiaires pour sécurité, cache ou équilibrage de charge sans modifier le client.
• Exemple : Un CDN ou une API Gateway authentifie et met en cache les réponses avant de toucher le service d’origine.
• Compromis : Débogage et traçabilité peuvent devenir plus difficiles à cause des couches supplémentaires.

Code on Demand (optionnel) : Le serveur peut envoyer du code exécutable au client (par ex. JavaScript).

• Objectif : Étendre dynamiquement les capacités du client sans mises à jour lourdes côté client.
• Exemple : Une API renvoyant un script pour visualiser des données spécifiques dans le navigateur.
• Compromis : Usage rare pour des raisons de sécurité, maintenance et contrôle de version du code exécuté côté client.

Références : Fielding 2000 (thèse de Roy Fielding) ; RFC 7234 pour les règles de cache HTTP.

Client-Server	Modularité et indépendance
Stateless	Scalabilité horizontale
Cacheable	Performance et réduction de charge
Uniform Interface	Simplicité d’interaction
Layered System	Flexibilité opérationnelle
Code on Demand	Extensibilité (optionnelle)

Comment se déroule le cycle requête-réponse d’une REST API ?

Le cycle requête‑réponse d’une API REST suit le modèle client envoie requête → serveur traite → serveur renvoie réponse; je décris ici chaque étape concrète et les bonnes pratiques associées.

Étapes clés :

• Construction de la requête — Je définis l’URL (ressource ciblée), la méthode HTTP (GET, POST, PUT, DELETE), les headers (Accept, Content-Type, Authorization) et éventuellement le body (données JSON). Le header Authorization transporte les informations d’authentification (ex. token Bearer).
• Transport via HTTP — Je transmets la requête sur TCP/IP en respectant RFC 7230/7231 (protocole HTTP/1.1 ou HTTP/2 selon implémentation).
• Traitement côté serveur — Je vérifie l’authentification, j’applique la validation des entrées, j’accède aux ressources (base de données, cache), puis j’exécute la logique métier. L’authentification refuse ou autorise l’accès selon les règles de sécurité.
• Génération de la réponse — Je retourne un status code HTTP, des headers (Content-Type, Cache-Control, Location si création) et un body (souvent JSON). Le status indique le résultat synthétique de l’opération.
• Actions côté client — Je gère les erreurs (lecture du body d’erreur), j’applique des stratégies de retry pour les erreurs temporaires, et j’utilise le cache (headers Cache-Control, ETag) pour réduire la latence.

Statuts HTTP usuels à connaître :

200	OK — Ressource renvoyée.
201	Created — Ressource créée (souvent avec header Location).
204	No Content — Succès sans body.
400	Bad Request — Erreur de validation.
401	Unauthorized — Authentification requise/échouée.
403	Forbidden — Accès refusé malgré authentification.
404	Not Found — Ressource inexistante.
409	Conflict — Conflit de version/unique constraint.
500	Internal Server Error — Erreur serveur inattendue.

Exemple complet (création de ressource) :

Requête

POST /api/users HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJ...
Content-Type: application/json
Accept: application/json

{"email":"alice@example.com","name":"Alice"}

Réponse attendue

HTTP/1.1 201 Created
Location: /api/users/123
Content-Type: application/json

{"id":123,"email":"alice@example.com","name":"Alice"}

Bonnes pratiques — Je privilégie l’idempotence pour PUT/DELETE, j’envoie des erreurs structurées (JSON avec fields code et message), et j’utilise headers pour cache et authentification. Conformément à RFC 7231 et au modèle REST (Roy Fielding, 2000), ces principes rendent les APIs prévisibles et robustes.

Quelle est l’anatomie d’une requête REST et exemples concrets ?

Je décris ici l’anatomie d’une requête REST pour vous permettre de construire et diagnostiquer des appels API robustes.

URL (endpoint) : L’URL identifie la ressource. Privilégiez les noms pluriels pour les collections (ex : /users) et l’identifiant pour une ressource (ex : /users/42). Utilisez des paths pour la hiérarchie (/users/42/orders). Evitez les verbes dans l’URL. Les query parameters servent au tri, filtre et pagination (ex : ?limit=20&sort=created_at:desc).

Méthodes HTTP : GET lit une ressource. POST crée une ressource et retourne souvent 201 Created. PUT remplace complètement une ressource (idempotent). PATCH modifie partiellement (non nécessairement idempotent, normalisé par RFC 5789). DELETE supprime.

Headers : Authorization transporte l’authentification (ex : Bearer token). Content-Type indique le format du corps (ex : application/json). Accept précise le format souhaité. Cache-Control contrôle la mise en cache. Les headers peuvent aussi transmettre versioning (ex : Accept: application/vnd.myapp.v2+json).

Body (payload) : Corps en JSON typique { « email »: « … », « name »: « … » }. Validez côté serveur et retournez 400 Bad Request avec détails si validation échoue. Contrôlez la taille des payloads (limites serveur, souvent configurées entre 1 et 10 MB selon l’infra). Préférez réponses concises et normalisées pour les erreurs (ex : { « error »: « email.invalid », « message »: « Email address is required » }).

Exemples concrets

A) GET /users/42 — Récupérer un utilisateur

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

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

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

B) POST /users — Créer un utilisateur

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJ...

{ "email": "bob@example.com", "name": "Bob" }

HTTP/1.1 201 Created
Location: /users/43
Content-Type: application/json

{ "id": 43, "email": "bob@example.com", "name": "Bob" }

C) PATCH /users/42 — Mettre à jour l’email

PATCH /users/42 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJ...

{ "email": "alice.new@example.com" }

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

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

/users/42	GET	Accept: application/json Authorization: Bearer <token>	—
/users	POST	Content-Type: application/json Authorization: Bearer <token>	{ « email »: « bob@example.com », « name »: « Bob » }
/users/42	PATCH	Content-Type: application/json Authorization: Bearer <token>	{ « email »: « alice.new@example.com » }

Prêt à concevoir ou améliorer votre REST API pour votre service ?

J’ai expliqué ce qu’est une REST API, pourquoi elle existe et comment elle fonctionne en pratique: les six contraintes de Fielding, le cycle requête-réponse, et l’anatomie d’une requête (URL, méthode, headers, body). En appliquant ces principes vous réduirez le couplage, améliorerez la scalabilité et faciliterez l’intégration de services tiers. Bénéfice concret: des APIs plus robustes, plus faciles à maintenir et à sécuriser pour votre business.

FAQ

• Qu’est-ce qui différencie REST d’une API SOAP ?
  REST est un style architectural basé sur HTTP et des ressources identifiées par des URLs; SOAP est un protocole standard XML avec enveloppe, opérations définies et plus de contraintes sur le transport. REST est souvent plus léger et plus simple à intégrer pour des services web modernes.
• Dois-je toujours respecter les six contraintes REST strictement ?
  Non. En pratique, on priorise souvent client-server, stateless et uniform interface. Certaines contraintes comme code on demand sont rares. L’important est d’appliquer les principes qui apportent un gain concret (scalabilité, simplicité, cache).
• Quand utiliser PUT plutôt que PATCH ?
  PUT remplace entièrement la ressource et doit être idempotent; PATCH applique une modification partielle. Utilisez PUT pour remplacements complets et PATCH pour mises à jour partielles (par ex. changer seulement l’email).
• Quels headers HTTP sont essentiels pour une API sécurisée ?
  Au minimum: Authorization (ex: Bearer token) pour l’authentification, Content-Type pour le format des données, et des headers de sécurité (Ex: Strict-Transport-Security côté serveur). Utilisez TLS pour chiffrer le transport.
• Comment gérer le caching sur une REST API ?
  Indiquez explicitement la cacheabilité via les headers Cache-Control et ETag. Cachez les réponses GET là où les données sont relativement stables; évitez de cacher des réponses contenant des données sensibles ou spécifiques à l’utilisateur sans validation.

 

 

A propos de l’auteur

Franck Scandolera — expert & formateur en Tracking avancé server-side, Analytics Engineering, Automatisation No/Low Code (n8n), intégration de l’IA en entreprise et SEO/GEO. Responsable de l’agence webAnalyste et de l’organisme de formation Formations Analytics. Références clients: Logis Hôtel, Yelloh Village, BazarChic, Fédération Française de Football, Texdecor. Dispo pour aider les entreprises => contactez moi.