24 - Glossaire : tous les termes REST API en un seul endroit

Ce que tu vas apprendre

Les définitions de plus de 40 termes lies au design REST API
Les liens vers les articles de la serie qui approfondissent chaque concept
Un point de référencé rapide quand tu oublies ce que signifie un acronyme

Prerequisites

Aucun. Ce glossaire est fait pour etre consulte a tout moment. Mais si tu as lu toute la serie depuis l'introduction, tu reconnaitra chaque terme.

Ce glossaire rassemble tous les termes techniques que j'ai utilises dans cette serie. Je l'ai écrit parce que j'en avais marre de chercher "c'est quoi deja un ETag" dans trois articles différents. Tout est ici, en ordre alphabetique, avec un lien vers l'article qui en parle en détail. Si tu cherches un terme et qu'il n'y est pas, c'est que j'ai oublie de l'ajouter -- fais-moi signe sur paltemps.fr.

202 Accepted

Code HTTP qui indique que la requête a ete acceptee pour traitement, mais que le traitement n'est pas termine. Utilise pour les opérations longues (génération de rapport, envoi de masse). Le client peut poller un endpoint de statut pour suivre la progression. Voir Performance.

304 Not Modified

Code HTTP retourne quand le serveur détecté que la ressource n'a pas change depuis la dernière requête du client (via ETag ou Last-Modified). Aucun body n'est renvoye, le client utilise sa copie locale. Voir Caching.

429 Too Many Requests

Code HTTP retourne quand le client a dépassé la limite de requêtes autorisees. Doit etre accompagne d'un header Retry-After. Voir Rate limiting.

API Key

Cle unique attribuee a un client pour s'authentifier auprès de l'API. Généralement envoyee dans un header (X-API-Key ou Authorization). Moins sécurisée qu'un token JWT mais plus simple a gerer pour les integrations machine-to-machine. Voir Authentification.

Backoff exponentiel

Stratégie de retry ou le delai entre chaque tentative augmente exponentiellement (1s, 5s, 30s, 2min...). Evite de surcharger un serveur deja en difficulte. Utilise dans la livraison de webhooks et les appels entre services. Voir Webhooks.

Batch endpoint

Endpoint qui accepte plusieurs identifiants en une seule requête (GET /users?ids=1,2,3) pour éviter le problème N+1 cote client. Voir Relations et Performance.

Bearer token

Schema d'authentification HTTP ou le token est envoye dans le header Authorization: Bearer <token>. Le token est souvent un JWT. Voir Authentification.

Cache-Control

Header HTTP qui definit les regles de mise en cache d'une réponse. Directives principales : public, private, max-age, no-cache, no-store, s-maxage. Voir Caching.

CDN (Content Delivery Network)

Réseau de serveurs distribues geographiquement qui cache les réponses de ton API pres des utilisateurs. Reduit la latence et decharge ton serveur. Voir Caching.

Connection pooling

Technique qui réutilisé les connexions a la base de donnees au lieu d'en ouvrir une nouvelle a chaque requête. Reduit la latence de connexion et limite le nombre de connexions simultanees. Voir Performance.

Contract testing

Tests automatises qui verifient que ta réponse API est conforme au schema défini dans ta spécification OpenAPI. Detecte les derives entre la spec et l'implementation. Voir Testing.

Mecanisme qui permet a un serveur d'autoriser les requêtes venant d'un domaine différent. Contrôle par des headers comme Access-Control-Allow-Origin. Voir CORS.

CRUD

Create, Read, Update, Delete. Les quatre opérations de base sur une ressource, correspondant aux verbes HTTP POST, GET, PUT/PATCH, DELETE. Voir Principes REST.

Dead letter queue

File d'attente ou atterrissent les messages (webhooks, événements) qui n'ont pas pu etre livres apres toutes les tentatives de retry. Permet une investigation manuelle et un rejeu. Voir Webhooks.

ETag

Header HTTP qui contient un identifiant unique pour une version spécifique d'une ressource (généralement un hash du contenu). Utilise avec If-None-Match pour les requêtes conditionnelles. Voir Caching.

Expand/Include

Paramètre de requête (?expand=customer,items) qui permet au client de choisir quelles relations embarquer dans la réponse, evitant le problème N+1 au niveau API. Voir Relations.

HATEOAS (Hypermedia As The Engine Of Application State)

Principe REST ou chaque réponse contient des liens vers les actions possibles, permettant au client de naviguer l'API sans connaître les URLs a l'avance. Voir HATEOAS.

Helmet

Package Express.js qui configure automatiquement les security headers HTTP (HSTS, X-Content-Type-Options, etc.). Voir Sécurité.

HMAC-SHA256

Algorithme de signature utilisant un secret partage. Utilise pour vérifier l'authenticite des payloads de webhooks. Le serveur signe le body, le client vérifié la signature. Voir Webhooks.

Idempotence

Propriété d'une opération qui produit le meme résultat qu'on l'exécuté une ou plusieurs fois. GET, PUT et DELETE sont idempotents. POST ne l'est pas. Essentiel pour les webhooks et les retries. Voir Webhooks.

JWT (JSON Web Token)

Token encode en base64 qui contient des claims (identité, rôles, expiration). Compose de trois parties : header, payload, signature. Utilise pour l'authentification stateless. Voir Authentification.

Last-Modified

Header HTTP qui indique la date de dernière modification d'une ressource. Utilise avec If-Modified-Since pour les requêtes conditionnelles. Moins precis qu'un ETag. Voir Caching.

Load testing

Tests de performance qui simulent plusieurs utilisateurs simultanees pour mesurer le comportement de l'API sous charge. Outils : k6, Artillery. Voir Testing.

Mass assignment

Vulnérabilité ou le client peut modifier des champs non autorises (comme role ou is_admin) en les incluant dans le body JSON. Se previent avec des schemas de validation explicites. Voir Sécurité.

multipart/form-data

Format d'encodage HTTP utilise pour envoyer des fichiers et des donnees mixtes dans une meme requête. Chaque partie a son propre Content-Type. Voir Upload.

N+1

Problème de performance ou le chargement de N éléments généré N requêtes supplementaires pour les relations. Se produit au niveau SQL (ORM) et au niveau HTTP (API). Voir Performance et Relations.

OAuth 2.0

Protocole d'autorisation qui permet a une application tierce d'acceder aux ressources d'un utilisateur sans connaître son mot de passe. Utilise des scopes, des tokens d'acces et des refresh tokens. Voir Authentification.

OpenAPI

Spécification (anciennement Swagger) qui decrit une API REST dans un format machine-readable (YAML/JSON). Permet de générer de la documentation, des clients, des mocks et des tests. Voir OpenAPI.

OWASP API Security Top 10

Liste des 10 vulnérabilités les plus critiques spécifiques aux APIs, publiee par l'OWASP. Inclut le broken object level authorization, le mass assignment, et l'absence de rate limiting. Voir Sécurité.

Pagination

Technique qui decoupe une grande liste de résultats en pages. Trois approches : offset/limit, cursor-based, keyset. Voir les premiers articles de la serie.

Preflight request

Requete OPTIONS envoyee automatiquement par le navigateur avant certaines requêtes cross-origin pour vérifier les permissions CORS. Voir CORS.

Presigned URL

URL temporaire générée par le serveur qui autorise un upload direct vers un service de stockage (S3) sans passer par le backend. Expire apres un delai configure. Voir Upload.

Rate limiting

Technique qui limite le nombre de requêtes qu'un client peut envoyer dans une fenêtre de temps. Algorithmes : token bucket, sliding window, fixed window. Voir Rate limiting.

Redoc

Outil de génération de documentation API à partir d'une spec OpenAPI. Produit une interface trois colonnes (navigation, description, exemples). Voir Documentation.

REST (Representational State Transfer)

Style d'architecture pour les APIs web base sur les resources, les verbes HTTP, et les representations (JSON, XML). Defini par Roy Fielding dans sa these de doctorat en 2000. Voir Introduction.

RFC 7807 (Problem Détails)

Standard qui definit un format JSON uniforme pour les erreurs HTTP, avec cinq champs : type, title, status, detail, instance. Content-Type : application/problem+json. Voir Erreurs.

Scalar

Outil de documentation API qui combine l'interactivite de Swagger UI et la lisibilité de Redoc. Genere des code examples dans plusieurs langages. Voir Documentation.

Sparse fieldsets

Paramètre de requête (?fields=id,name,avatar) qui permet au client de sélectionner uniquement les champs dont il a besoin, reduisant la taille de la réponse. Voir Relations.

Streaming

Technique d'envoi de donnees ou le serveur écrit la réponse au fur et a mesure au lieu de tout charger en mémoire. Utilise Transfer-Encoding: chunked. Voir Performance et Upload.

Sub-resource

Ressource qui n'existe que dans le contexte d'un parent (/orders/42/items). Ne devrait pas dépasser deux niveaux d'imbrication. Voir Relations.

Swagger UI

Outil historique de documentation API interactive générée depuis une spec OpenAPI. Permet de tester les endpoints directement dans le navigateur. Voir Documentation.

Token bucket

Algorithme de rate limiting base sur un seau de jetons. Chaque requête consomme un jeton, les jetons se regenerent a un rythme constant. Autorise les bursts quand le seau est plein. Voir Rate limiting.

Versioning

Stratégie pour faire évoluer une API sans casser les clients existants. Approches : URI (/v2/users), header (Accept-Version: 2), query param (?version=2). Voir Versioning.

Webhook

Callback HTTP envoye par ton API vers une URL du client quand un événement se produit. Inverse du polling : le serveur notifie le client au lieu que le client interroge le serveur. Voir Webhooks.

Article précédent : Sécurité