Accueil › Glossaire › REST API

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.

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).

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).

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.

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.

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.

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

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 :

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é.

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.