REST API

Une REST API (Representational State Transfer Application Programming Interface) est une interface de programmation qui respecte les principes architecturaux REST pour permettre la communication entre applications via le protocole HTTP, en exposant des ressources identifiées par des URL et manipulées via des méthodes HTTP standard (GET, POST, PUT, DELETE).

REST est le style d’architecture dominant pour les API web. Quand vous interagissez avec l’API de Stripe, GitHub, OpenAI, Anthropic, ou de la quasi-totalité des services en ligne, vous utilisez une REST API. Sa force : la simplicité. Elle utilise le protocole HTTP que tout le monde connaît, du JSON comme format de données, et des conventions prévisibles pour les URL et les méthodes. En 2026, malgré l’émergence de GraphQL et gRPC, REST reste le choix par défaut pour la majorité des API web.

Catégorie: Style d’architecture API
Créateur: Roy Fielding (thèse doctorale, 2000)
Protocole: HTTP / HTTPS
Format de données: JSON (dominant), XML
Spécification: OpenAPI 3.1 (documentation et validation)
Alternatives: GraphQL, gRPC, WebSocket

Les principes REST

REST n’est pas un protocole ni un standard. C’est un style architectural défini par six contraintes :

Client-serveur. Le client (frontend, mobile, autre service) et le serveur (backend, API) sont séparés et évoluent indépendamment. Le client ne sait rien de l’implémentation du serveur, et vice-versa.

Sans état (stateless). Chaque requête contient toutes les informations nécessaires à son traitement. Le serveur ne stocke aucun état de session entre les requêtes. Cela simplifie le scaling horizontal : n’importe quel serveur peut traiter n’importe quelle requête.

Interface uniforme. Les ressources sont identifiées par des URL, manipulées via des méthodes HTTP standard, et représentées dans un format commun (JSON). Cette uniformité rend les API prévisibles et auto-documentées.

Cacheable. Les réponses doivent indiquer si elles sont cachables ou non (via les headers HTTP Cache-Control, ETag). Le cache réduit la charge serveur et améliore la latence.

Système en couches. Le client ne sait pas s’il parle directement au serveur ou à un intermédiaire (load balancer, cache, API gateway). Cette transparence permet d’ajouter des couches d’infrastructure sans modifier le client.

Code à la demande (optionnel). Le serveur peut envoyer du code exécutable au client (JavaScript, par exemple). Ce principe est rarement utilisé dans les API modernes.

Les méthodes HTTP

REST utilise les méthodes (verbes) HTTP pour définir les actions sur les ressources. C’est le cœur du design REST : les URL représentent les ressources (noms), les méthodes HTTP représentent les actions (verbes).

Méthode	Action	Exemple	Idempotent	Body
GET	Lire une ressource ou une collection	`GET /users/123`	Oui	Non
POST	Créer une nouvelle ressource	`POST /users`	Non	Oui
PUT	Remplacer une ressource entière	`PUT /users/123`	Oui	Oui
PATCH	Modifier partiellement une ressource	`PATCH /users/123`	Non*	Oui
DELETE	Supprimer une ressource	`DELETE /users/123`	Oui	Non

L’idempotence est un concept clé : une requête idempotente produit le même résultat qu’elle soit exécutée une ou plusieurs fois. GET, PUT et DELETE sont idempotents. POST ne l’est pas (deux POST identiques créent deux ressources).

Design des URL

Les URL d’une REST API bien conçue sont prévisibles et auto-documentées. Les conventions :

Utilisez des noms, pas des verbes. /users (correct) et non /getUsers (incorrect). L’action est portée par la méthode HTTP, pas par l’URL.

Utilisez le pluriel pour les collections. /users pour la collection, /users/123 pour un élément spécifique.

Imbriquez pour les relations. /users/123/orders pour les commandes de l’utilisateur 123. Limitez l’imbrication à 2-3 niveaux maximum pour rester lisible.

Versionnez. /v1/users ou /v2/users. Le versionnement via l’URL est le plus répandu et le plus simple. Alternative : versionnement via un header HTTP (Accept: application/vnd.api+json;version=2).

# Exemples d'URL REST bien conçues
GET    /v1/models                    # Lister tous les modèles
POST   /v1/models                    # Créer un nouveau modèle
GET    /v1/models/gpt-5              # Détails d'un modèle
PUT    /v1/models/gpt-5              # Remplacer un modèle
DELETE /v1/models/gpt-5              # Supprimer un modèle
GET    /v1/models/gpt-5/versions     # Versions d'un modèle
POST   /v1/chat/completions          # Créer une complétion (OpenAI style)

Les codes de statut HTTP

Les codes de statut HTTP communiquent le résultat de la requête. Utilisez-les correctement : un API qui retourne toujours 200 avec un champ error dans le body est un anti-pattern.

Code	Signification	Usage typique
200 OK	Succès (GET, PUT, PATCH)	Réponse standard de succès
201 Created	Ressource créée (POST)	Retourne la ressource créée
204 No Content	Succès sans body (DELETE)	Suppression réussie
400 Bad Request	Requête malformée	JSON invalide, champ manquant
401 Unauthorized	Non authentifié	Token manquant ou expiré
403 Forbidden	Authentifié mais non autorisé	Pas les permissions requises
404 Not Found	Ressource inexistante	ID invalide, URL incorrecte
429 Too Many Requests	Rate limit dépassé	Rate limiting
500 Internal Server Error	Erreur serveur	Bug, crash, dépendance indisponible

REST API dans l’IA et le ML

Les REST API sont le mécanisme standard pour interagir avec les services d’IA en production.

API des fournisseurs LLM

OpenAI, Anthropic, Google, Mistral exposent leurs modèles via des REST API. L’endpoint POST /v1/chat/completions (convention OpenAI devenue standard de facto) est utilisé par des millions d’applications pour générer du texte. La requête contient les messages et les paramètres, la réponse contient la complétion générée.

# Appel à l'API Claude (Anthropic)
curl -X POST https://api.anthropic.com/v1/messages 
  -H "Content-Type: application/json" 
  -H "x-api-key: $ANTHROPIC_API_KEY" 
  -H "anthropic-version: 2023-06-01" 
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Expliquez REST API en une phrase."}
    ]
  }'

API de model serving

Les modèles ML déployés en production sont exposés via des REST API (ou gRPC pour les communications internes). KServe, BentoML, Triton et vLLM exposent des endpoints REST pour l’inférence. La convention v1/predict (KServe) ou v1/chat/completions (compatible OpenAI) est devenue standard pour le serving de modèles.

API dans les pipelines MLOps

Les outils MLOps (MLflow, Weights & Biases, feature stores) exposent des REST API pour la gestion programmatique : enregistrement d’expériences, promotion de modèles, récupération de features. Les webhooks utilisent des callbacks REST pour notifier les événements (entraînement terminé, drift détecté).

Authentification et sécurité

Les principaux mécanismes d’authentification pour les REST API :

API Key. Une clé unique passée dans un header (Authorization: Bearer sk-xxx ou un header custom comme x-api-key). Simple mais offre peu de granularité. C’est le mécanisme utilisé par OpenAI, Anthropic et la plupart des API de LLM.

OAuth 2.0. Le standard pour l’authentification déléguée. Le client obtient un access token (de courte durée) auprès d’un serveur d’autorisation, puis l’utilise pour accéder à l’API. Plus complexe, mais supporte les scopes (permissions granulaires) et le refresh token.

JWT (JSON Web Tokens). Un token auto-contenu qui encode les informations d’authentification (utilisateur, permissions, expiration). Le serveur n’a pas besoin de consulter une base de données pour valider le token, ce qui le rend adapté aux architectures microservices.

HTTPS est obligatoire Ne servez jamais une REST API sur HTTP en clair en production. Les API Keys, tokens OAuth et JWT transitent dans les headers : sans HTTPS, ils sont interceptables par n’importe quel intermédiaire réseau. HTTPS est le minimum non négociable.

Pagination, filtrage et tri

Les collections (listes de ressources) doivent supporter la pagination pour éviter de retourner des milliers d’éléments en une seule réponse. Deux approches principales :

Offset-based : GET /users?page=2&per_page=20. Simple et intuitif. Inconvénient : les résultats sont instables si des éléments sont ajoutés/supprimés entre les requêtes.

Cursor-based : GET /users?after=cursor_abc&limit=20. Le curseur pointe vers un élément spécifique. Plus robuste et performant pour les grands datasets. C’est l’approche recommandée pour les API modernes.

Le filtrage (?status=active&role=admin), le tri (?sort=created_at&order=desc) et la sélection de champs (?fields=id,name,email) sont des bonnes pratiques qui réduisent le trafic réseau et améliorent la performance.

Documentation avec OpenAPI

OpenAPI (anciennement Swagger) est le standard pour documenter les REST API dans un format lisible par les machines (YAML/JSON). À partir d’une spécification OpenAPI, vous pouvez générer automatiquement de la documentation interactive (Swagger UI, Redoc), des SDKs clients, et de la validation de requêtes.

La documentation générée depuis OpenAPI reste synchronisée avec l’API réelle, éliminant le problème classique de la documentation manuelle qui se périme. Les études montrent qu’une bonne documentation réduit le temps d’intégration d’environ 40%.

REST vs les alternatives

Aspect	REST	GraphQL	gRPC
Protocole	HTTP/1.1 ou HTTP/2	HTTP (POST unique)	HTTP/2
Format	JSON, XML	JSON	Protocol Buffers (binaire)
Flexibilité requête	Fixe par endpoint	Le client choisit les champs	Fixe par service
Performance	Bonne	Bonne (moins d’over-fetching)	Excellente (binaire, streaming)
Streaming	Limité (SSE)	Subscriptions	Natif (bidirectionnel)
Typage	Optionnel (OpenAPI)	Schema obligatoire	Protobuf obligatoire (fort)
Cas d’usage	API publiques, CRUD, web	Frontends complexes, mobile	Inter-services, haute perf
Adoption	Dominante	Croissante	Services internes

La règle pratique : utilisez REST pour les API publiques et les cas simples. Considérez GraphQL quand vos clients (surtout mobile) ont besoin de flexibilité dans les données récupérées. Utilisez gRPC pour les communications inter-services à haute performance dans une architecture microservices.

Format de réponse et gestion des erreurs

Un format de réponse cohérent est essentiel pour l’expérience développeur. Les réponses de succès et d’erreur doivent suivre la même structure :

// Réponse de succès
{
  "data": {
    "id": "usr_abc123",
    "name": "Alice Martin",
    "email": "alice@example.com",
    "created_at": "2026-03-20T10:30:00Z"
  }
}

// Réponse de collection avec pagination
{
  "data": [
    {"id": "usr_abc123", "name": "Alice Martin"},
    {"id": "usr_def456", "name": "Bob Dupont"}
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "total_pages": 8
  }
}

// Réponse d'erreur
{
  "error": {
    "type": "validation_error",
    "message": "Le champ email est requis.",
    "code": "missing_field",
    "param": "email",
    "doc_url": "https://api.example.com/docs/errors#missing_field"
  }
}

La clé d’une bonne gestion des erreurs : un message clair qui dit exactement ce qui ne va pas et comment le corriger, le bon code HTTP (400 pour une erreur client, 500 pour une erreur serveur), et un code d’erreur machine-readable pour que le client puisse gérer l’erreur programmatiquement. Stripe est la référence en matière de design d’erreurs API : chaque erreur inclut un type, un message humain, un code machine et un lien vers la documentation.

Bonnes pratiques REST API

Versionnez dès le jour 1. Même si vous n’avez qu’une seule version, commencez par /v1/. Vous remercierez votre vous du passé quand vous devrez introduire des changements non rétrocompatibles.

Paginatez les collections. Fixez une limite par défaut (20-100 éléments) et une limite maximum. Retournez les métadonnées de pagination (total, page courante, pages totales, liens next/prev) dans la réponse.

Utilisez des réponses cohérentes. Enveloppez les données dans un objet data et les erreurs dans un objet error. Toujours le même format, quelle que soit la route.

Documentez avec OpenAPI. Générez la spec OpenAPI automatiquement depuis votre code (FastAPI le fait nativement) ou maintenez-la en parallèle. La documentation interactive (Swagger UI) est le premier point de contact pour les développeurs qui intègrent votre API.

Implémentez le rate limiting. Protégez votre API contre les abus avec un rate limiting par clé API. Retournez les headers standard (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) pour que les clients puissent s’adapter.

Supportez le CORS correctement. Si votre API est appelée depuis un navigateur, configurez les headers CORS (Cross-Origin Resource Sharing) pour autoriser les origines légitimes. Un CORS mal configuré est soit un blocage pour les développeurs frontend, soit une faille de sécurité.

FastAPI : le framework REST Python de référence Si vous développez une REST API en Python (courant en ML/IA), FastAPI est le choix recommandé. Il génère automatiquement une documentation OpenAPI interactive, supporte la validation des requêtes via Pydantic, est async-native (haute performance), et s’intègre naturellement avec les outils ML. Flask et Django REST Framework restent populaires mais FastAPI offre le meilleur rapport productivité/performance pour les nouveaux projets.

Erreurs courantes

Verbes dans les URL. /getUsers, /deleteOrder/123 : les URL doivent contenir des noms (ressources), pas des verbes. Utilisez GET /users et DELETE /orders/123.

Toujours retourner 200. Retourner 200 avec {"error": "not found"} au lieu de 404 force le client à parser le body pour détecter les erreurs. Utilisez les codes HTTP correctement.

Pas de pagination. Un endpoint qui retourne 10 000 résultats d’un coup est un incident de performance en attente. Ajoutez la pagination dès le premier jour.

Pas de versionnement. Sans versionnement, toute modification de l’API casse potentiellement les clients existants. Versionnez via l’URL (/v1/) dès la première version.

Exposer les IDs internes. Les IDs auto-incrémentés de votre base de données sont prévisibles et révèlent des informations (nombre de clients, fréquence de création). Utilisez des UUID ou des identifiants opaques.

Questions fréquentes sur les REST API

Quelle est la différence entre REST et une API ?

Une API (Application Programming Interface) est un concept générique : toute interface qui permet à deux logiciels de communiquer. REST est un style d’architecture spécifique pour concevoir des API web, basé sur HTTP, des ressources identifiées par URL, et des méthodes HTTP standard. Toutes les REST API sont des API, mais toutes les API ne sont pas REST. SOAP, GraphQL, gRPC sont d’autres styles d’API.

REST API vs GraphQL : lequel choisir ?

REST pour la simplicité, les API publiques et les cas CRUD standards. GraphQL quand vos clients ont des besoins de données très variables (éviter l’over-fetching et l’under-fetching), typiquement pour des applications mobile ou des frontends complexes avec de multiples vues. GraphQL ajoute de la complexité (schema, resolvers, gestion du cache) qui n’est justifiée que si la flexibilité est un besoin réel.

Comment sécuriser une REST API ?

Quatre fondamentaux : (1) HTTPS obligatoire (chiffrement du transport), (2) authentification sur chaque requête (API Key, OAuth 2.0, JWT), (3) rate limiting pour prévenir les abus (429 Too Many Requests), (4) validation des entrées pour prévenir les injections. En entreprise, ajoutez des contrôles d’accès granulaires (RBAC), du logging et de l’audit, et considérez une approche Zero Trust (vérification à chaque requête, même interne).

Les API des LLM (OpenAI, Anthropic) sont-elles des REST API ?

Oui, dans leur forme de base. Les API d’OpenAI, Anthropic, Google et Mistral utilisent des endpoints HTTP avec des requêtes POST et des réponses JSON, ce qui est conforme aux principes REST. Cependant, le streaming des réponses utilise les Server-Sent Events (SSE), qui est une extension du modèle request-response classique. Les SDKs clients (Python, TypeScript) abstraient ces détails pour le développeur.

Combien de requêtes par seconde une REST API peut-elle gérer ?

Cela dépend entièrement de l’implémentation, pas du style REST lui-même. Un serveur FastAPI simple sur un seul CPU peut gérer quelques milliers de requêtes par seconde. Avec du caching, du load balancing et du scaling horizontal (via Kubernetes), des REST API servent des millions de requêtes par seconde. Les API des grands fournisseurs (Stripe, Twilio, AWS) démontrent que REST scale à n’importe quelle charge avec la bonne architecture.