Comment fonctionne une API REST et à quoi sert-elle ?

Une API REST est un style architectural qui standardise les échanges HTTP entre systèmes pour les rendre prévisibles et scalables, défini par Roy Fielding en 2000. Je détaille les contraintes clés, le cycle requête‑réponse et l’anatomie d’une requête pour une mise en œuvre pratique.

Quel problème REST résout-il

REST résout le problème d’interopérabilité et de prédictibilité entre systèmes hétérogènes (frontends, backends, services tiers) en imposant des conventions d’échanges via HTTP.

Contexte et besoin : Les applications modernes assemblent des composants écrits dans des langages différents, déployés sur des serveurs distincts et fournis par des tiers (par exemple authentification via Google, paiements via Stripe, données météo via OpenWeatherMap). Je m’appuie sur la thèse de Roy Fielding (2000) qui définit REST comme un ensemble de contraintes architecturales pour rendre les services Web simples et scalables. Je m’appuie aussi sur la documentation MDN sur HTTP qui explicite les méthodes (GET, POST, PUT, DELETE) et les codes de statut utilisés pour standardiser les échanges. Je note que l’écosystème d’APIs est massif : ProgrammableWeb recense plus de 24 000 APIs publiques, ce qui illustre la croissance des architectures distribuées (source : programmableweb.com).

• Conséquences pratiques du problème : Les systèmes hétérogènes génèrent des difficultés de compatibilité quand un contrat API change, des limites de montée en charge si l’état est stocké côté serveur, et une complexité accrue pour le versioning et la maintenance.
• Exemple d’incident plausible : Une modification du format JSON renvoyé par un fournisseur tiers peut casser le parsing côté client et bloquer des paiements ou des connexions.
• Comment REST réduit ces risques : REST impose des méthodes HTTP standardisées, des codes de statut explicites et des ressources identifiables, ce qui rend les contrats plus prévisibles et les régressions plus localisables.

Cas d’usage concrets :

• Login via OAuth : Le client (application) redirige l’utilisateur vers le serveur d’autorisation (Google). Le serveur d’autorisation émet un token via endpoints REST (GET/POST) que le client utilise ensuite pour appeler les APIs protégées.
• Paiement Stripe : Le client appelle l’API REST de Stripe pour créer une intention de paiement (POST). Le serveur Stripe valide la demande, renvoie un statut et des ressources (payment intent) que le client suit.
• Récupération météo : Le client envoie une requête GET sur l’API météo. Le serveur retourne un JSON avec température et prévisions et des codes HTTP qui indiquent l’état de la requête.

Conclusion : REST offre une réponse pragmatique en standardisant échanges et contrats pour faciliter l’interopérabilité, la scalabilité et la maintenance.

Critère	Sans état (REST)	État côté serveur
Scalabilité	Élevée, car chaque requête est indépendante et les serveurs peuvent être ajoutés facilement.	Moins élevée, car la réplication/partage d’état nécessite synchronisation ou sticky sessions.
Complexité	Modérée, nécessité de gérer l’état côté client ou via tokens mais logique serveur simplifiée.	Plus élevée, nécessité de stocker et synchroniser l’état utilisateur sur le serveur.
Persistance de session	Faible, la session n’est pas stockée serveur ; on utilise des tokens (JWT) ou cookies signés.	Forte, la session est conservée côté serveur, facilitant certains scénarios mais limitant l’élasticité.

Qu’est-ce qu’une API REST

Une API REST est un contrat d’échange basé sur des contraintes architecturales appliquées sur HTTP, visant à rendre les interfaces prévisibles, stateless et cacheables.

Je distingue trois notions souvent confondues : API comme contrat d’échange décrivant les opérations, les formats et les erreurs ; REST comme un ensemble de contraintes architecturales (ressources identifiables, uniformité d’interface, stateless, cacheabilité, architecture en couches, code à la demande optionnel) défini par Roy Fielding dans sa thèse (2000) (https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) ; et HTTP comme protocole de transport et de sémantique (méthodes GET/POST/PUT/DELETE, codes de statut) normalisé dans la RFC 7231 (https://datatracker.ietf.org/doc/html/rfc7231) et documenté sur MDN (https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview).

Je précise pourquoi ces distinctions comptent pour un développeur ou un architecte : le contrat (API) oriente la documentation et les tests automatisés ; REST impose des contraintes qui facilitent la scalabilité et le cache ; et HTTP fournit des primitives (méthodes, en-têtes, codes) permettant une implémentation standardisée et observable. Ces différences impactent le design des routes, la stratégie de tests (contrats, contrats consumer-driven), la montée en charge (stateless facilite le load balancing) et la compatibilité descendante (utilisation des codes HTTP et Content-Type).

Je donne des usages concrets et leur correspondance avec les avantages REST :

• Récupération de données : GET pour ressources lisibles, avantage = prévisibilité et cacheabilité (ex. OpenWeather API, https://openweathermap.org/api).
• Authentification et autorisation : flux OAuth sur endpoints REST, avantage = compatibilité et interopérabilité (ex. Google OAuth, https://developers.google.com/identity/protocols/oauth2).
• Paiements et opérations transactionnelles : endpoints idempotents et status codes clairs, avantage = fiabilité et scalabilité (ex. Stripe API, https://stripe.com/docs/api).

Je propose une checklist courte pour décider si une API doit être RESTful :

• Les clients sont nombreux et hétérogènes, et l’uniformité d’interface apporte un vrai gain.
• Les interactions peuvent être modélisées comme des ressources identifiables (URI) distinctes.
• Les opérations peuvent rester stateless ou externaliser l’état via tokens/ressources.
• Le cache côté client/infra améliore sensiblement les performances.
• La sémantique HTTP (méthodes, codes) suffit pour exprimer besoins métier sans inventer un protocole.

Cette mise en place des définitions et des usages conduit naturellement à détailler maintenant chacune des contraintes REST.

Quelles sont les contraintes REST

Les six contraintes REST sont Client-Server, Statelessness, Cacheability, Uniform Interface, Layered System et Code on Demand (optionnel).

Je détaille ci‑dessous chaque contrainte avec définition, exemple, bénéfices et limites.
Voici les contraintes et leur application :

• Client‑Server. Définition : Je sépare l’interface utilisateur du stockage et de la logique métier. Exemple : Une SPA (Single Page Application) consomme une API backend distincte. Bénéfices : Séparation des préoccupations, déploiement indépendant, meilleure maintenabilité. Limitations : Latence réseau accrue et nécessité de gérer l’authentification entre domaines.
• Statelessness. Définition : Je n’entretiens pas d’état de session côté serveur entre requêtes. Exemple : Jeton JWT envoyé dans l’en‑tête Authorization pour chaque requête. Bénéfices : Scalabilité horizontale simple, failover facilité. Limitations : Taille des tokens, complexité d’invalidation et gestion des permissions.

  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

• Cacheability. Définition : Je permets la mise en cache explicite des réponses via HTTP. Exemple : En‑têtes Cache‑Control, ETag et Last‑Modified. Bénéfices : Réduction de la latence et de la charge serveur. Limitations : Risque de données obsolètes, complexité des règles de validation.
• Uniform Interface. Définition : Je standardise l’accès aux ressources via URI, méthodes HTTP (GET, POST, PUT, DELETE), et représentations (JSON). Exemple : GET /users/123 retourne une représentation JSON. Bénéfices : Simplicité pour les clients, interopérabilité. Limitations : Malentendus sur le bon usage des verbes HTTP et gestion des erreurs.
• Layered System. Définition : Je permets une architecture en couches (proxy, load‑balancer, gateway). Exemple : CDN devant l’API pour accélérer les réponses statiques. Bénéfices : Sécurité, scalabilité, résilience. Limitations : Complexité de débogage et visibilité réduite sur la chaîne de requêtes.
• Code on Demand (optionnel). Définition : Je peux envoyer du code exécutable au client. Exemple : Serveur retournant un script JavaScript pour transformer une représentation. Bénéfices : Flexibilité côté client. Limitations : Risques de sécurité, complexité et rare adoption.

Observations courantes : La plupart des API respectent Client‑Server, Statelessness (souvent partiellement) et Uniform Interface ; Cacheability et Layered System sont appliquées selon les besoins ; Code on Demand est rarement utilisé (voir MDN Web Docs sur REST).

Code on Demand est rarement déployé en production en raison des problèmes de sécurité (CSP, injection) et de testing ; un exemple hypothétique serait un serveur qui envoie un script pour exécuter une validation client spécifique pour une application hors ligne.

Client-Server	Séparation, Déploiement
Statelessness	Scalabilité, Simplicité
Cacheability	Performance, Réduction‑charge
Uniform Interface	Interopérabilité, Simplicité
Layered System	Sécurité, Résilience
Code on Demand	Flexibilité, Risque

Cette compréhension des contraintes prépare directement le cycle requête‑réponse et son comportement concret.

Comment fonctionne le cycle requête-réponse

Le cycle requête-réponse REST suit un schéma simple où le client envoie une requête HTTP identifiant une ressource, le serveur la traite et renvoie une réponse avec statut et payload.

J’envoie une requête HTTP depuis le client contenant l’URL (Uniform Resource Locator) qui identifie la ressource, la méthode HTTP (GET, POST, PUT, DELETE), des headers (par exemple Accept, Authorization) et éventuellement un body JSON pour les méthodes qui l’acceptent.

Le réseau effectue la résolution DNS, établit une connexion TCP/TLS et transporte les paquets. La latence réseau et les retransmissions TCP peuvent impacter la durée totale.

Le serveur reçoit la requête, applique le routage, vérifie l’authentification/autorisations, exécute la logique métier et interroge les données persistantes. Le serveur construit ensuite une réponse composée d’un code de statut HTTP, de headers (Content-Type, Cache-Control, Location) et d’un payload (souvent JSON).

Le réseau renvoie la réponse au client en respectant les mêmes couches TCP/TLS/DNS. Le client interprète le code de statut, lit les headers et consomme le payload ou traite l’erreur.

Les codes de statut HTTP indiquent l’issue opérationnelle de la requête. Le tableau ci‑dessous résume les codes fréquemment utilisés et leur sens pratique.

200	Succès général ; corps de réponse présent pour la ressource demandée.
201	Ressource créée ; inclure Location vers la nouvelle ressource.
204	Succès sans contenu (par ex. suppression réussie).
400	Requête malformée ; erreur côté client (validation).
401	Non authentifié ; authentification requise ou invalide.
403	Interdit ; authentifié mais pas autorisé.
404	Ressource non trouvée.
500	Erreur serveur générique ; bug ou indisponibilité interne.

La latence et les timeouts définissent combien de temps on attend une réponse. Le retry automatise une nouvelle tentative mais nécessite idempotence — propriété garantissant que répéter une opération a le même effet que l’exécuter une fois. Les méthodes GET, PUT et DELETE sont idempotentes ; POST ne l’est pas par défaut. Le caractère stateless d’une API REST signifie que le serveur ne conserve pas d’état de session, ce qui simplifie la scalabilité mais complique les transactions distribuées (on utilise alors des compensations ou des patterns comme Sagas).

curl -i -H "Accept: application/json" https://api.example.com/users/42
# Réponse attendue: HTTP/1.1 200 OK
# Content-Type: application/json
# Body: {"id":42,"name":"Alice"}

La commande précédente effectue un GET qui demande JSON via Accept. Le client s’attend à un 200 avec un payload JSON contenant la ressource.

curl -i -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"name":"Bob","email":"bob@example.com"}'
# Réponse attendue: HTTP/1.1 201 Created
# Location: /users/43

La commande POST crée une ressource. Le header Content-Type indique le format du body JSON, Authorization porte le jeton, et la réponse 201 doit fournir Location vers la nouvelle ressource.

Checklist de bonnes pratiques pour erreurs et résilience :

• Utiliser des codes de statut explicites et messages JSON structurés pour l’erreur.
• Implémenter des retries clients avec backoff exponentiel et jitter pour éviter l’effet avalanche.
• Favoriser l’idempotence (ou tokens d’idempotence) pour opérations potentiellement répétées.
• Respecter Retry-After pour indiquer aux clients quand retenter.
• Mettre en place du monitoring, des logs corrélés par trace-id et des alertes temps réel.

Pour référence technique, consulter MDN sur les status HTTP et la RFC 7231 (https://developer.mozilla.org/ et https://datatracker.ietf.org/doc/html/rfc7231).

Quelle est l’anatomie d’une requête REST

Une requête REST se compose d’une URL (endpoint), d’une méthode HTTP, d’en-têtes (headers) et, si nécessaire, d’un corps (body).

Une URL/endpoint contient plusieurs parties : le scheme (http/https), le host (api.exemple.com), le base path (/v1), le resource path (/users/123) et éventuellement des query params (?active=true).

• Respecter le style RESTful : noms pluriels (users), hiérarchie claire (/users/123/orders), éviter les verbes dans l’URL (pas /getUser).
• Exemple liste : https://api.example.com/v1/users
• Exemple ressource unique : https://api.example.com/v1/users/123
• Exemple filtre via query : https://api.example.com/v1/users?role=admin&active=true

Les méthodes HTTP portent la sémantique de l’action. Je différencie :

Méthode	Action	Idempotence	Code typique
GET	Lire une ressource	Oui	200
POST	Créer une ressource	Non	201
PUT	Remplacer/mettre à jour	Oui	200/204
PATCH	Modifier partiellement	Souvent non garanti	200/204
DELETE	Supprimer	Oui	204

Les en-têtes essentiels contrôlent l’authentification, le format et le cache. Je recommande :

• Authorization : Bearer ou une API key selon l’API.
• Content-Type : application/json pour les corps JSON.
• Accept : préférer application/json pour la réponse.
• Cache-Control et ETag : gérer le cache et la validation côté client/serveur.

Example:
ETag: "v2"
If-None-Match: "v2"  # Retour 304 si inchangé

Le corps s’utilise pour POST/PUT/PATCH. Je privilégie JSON et des schémas (OpenAPI/JSON Schema) pour la validation. Gérer proprement les erreurs 400 avec un payload décrivant les violations.

Example JSON minimal (création utilisateur):
{
  "email": "alice@example.com",
  "name": "Alice Dupont",
  "password": "••••••••"
}

Exemples concrets :

curl -i -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","name":"Alice Dupont","password":"pwd"}'
# Réponse attendue :
# HTTP/1.1 201 Created
# Location: /v1/users/123

curl -i -X GET https://api.example.com/v1/users/123 \
  -H "Accept: application/json"
# Réponse attendue :
# HTTP/1.1 200 OK
# Content-Type: application/json
# {"id":123,"email":"alice@example.com","name":"Alice Dupont"}

Élément	Rôle
URL/Endpoint	Identifier ressource
Méthode HTTP	Action sémantique
En-têtes	Meta/ sécurité
Corps	Données
Query params	Filtrage

Références : MDN Web Docs (HTTP methods, headers), RFC 7231 (semantics), RFC 7232 (ETag), OpenAPI Specification.

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

J’ai résumé ce qu’est une API REST, pourquoi elle existe, ses six contraintes, le cycle requête‑réponse et l’anatomie d’une requête. En respectant les principes REST (séparation client/serveur, statelessness, interface uniforme) vous gagnez en scalabilité, maintenance et interopérabilité. Appliquez les bonnes pratiques exposées (méthodes HTTP, headers, codes) pour obtenir une API prévisible et résiliente — bénéfice direct : moins de bugs, déploiements plus rapides et intégrations tierces simplifiées.

FAQ

• Qu’est-ce qui différencie une API REST d’une API SOAP ?
  REST est un style architectural basé sur HTTP et des ressources, privilégiant la simplicité, le JSON et la scalabilité. SOAP est un protocole plus formel utilisant XML, avec des spécifications sur la sécurité et les transactions. REST est généralement préféré pour les APIs web modernes.
• Une API REST doit-elle absolument être stateless ?
  La contrainte stateless est centrale à REST : chaque requête contient toutes les informations nécessaires. Cela facilite la scalabilité et le routage. Dans la pratique, on combine souvent le statelessness avec des mécanismes externes (tokens, caches, sessions distribuées) pour les besoins métiers.
• Quand utiliser PATCH plutôt que PUT ?
  Utilisez PUT pour remplacer entièrement une ressource et PATCH pour des mises à jour partielles. PATCH est utile pour modifications locales (quelques champs) et réduit la taille des payloads; attention à la gestion de l’idempotence.
• Comment sécuriser une API REST en production ?
  Sécurisez via HTTPS, tokens JWT ou OAuth2 pour l’authentification, scopes pour l’autorisation, validation côté serveur des inputs, rate limiting, et audits/monitoring. Référez-vous aux bonnes pratiques OAuth2 et à la documentation des fournisseurs pour implémentation.
• REST ou GraphQL : que choisir pour un nouveau projet ?
  Choisissez REST si vous voulez simplicité, cacheabilité HTTP et contrats clairs par ressource. Préférez GraphQL si vous avez des besoins clients très variés sur les données et voulez réduire le sur- et sous-fetching. Parfois une combinaison des deux est la meilleure option.

 

 

A propos de l’auteur

Je suis Franck Scandolera, expert & formateur en Tracking avancé server-side, Analytics Engineering, Automatisation No/Low Code (n8n) et intégration de l’IA en entreprise. Responsable de l’agence webAnalyste et de l’organisme de formation Formations Analytics, j’accompagne des clients comme Logis Hôtel, Yelloh Village, BazarChic, la Fédération Française de Football ou Texdecor. Disponible pour aider les entreprises à concevoir des APIs et architectures scalables — contactez-moi.