Comprendre REST : les principes derrière une API web

Une API renvoie des commandes en JSON et utilise GET ou POST. Ces choix ne disent pas encore comment ses clients découvrent les actions, utilisent le cache ou résistent aux évolutions du serveur. REST décrit cet ensemble de règles d'architecture. Comprendre leur rôle permet de choisir ce que votre API doit garantir, au-delà du format de ses réponses.

Un style d'architecture est un ensemble de contraintes

Un style d'architecture est un ensemble de règles choisies pour obtenir certaines propriétés. REST, pour Representational State Transfer, décrit notamment la séparation entre clients et serveurs, l'usage du cache et une interface commune. Roy Fielding l'a formalisé dans sa thèse publiée en 2000.

Le travail de Fielding accompagne l'évolution du Web et de HTTP dans les années 1990. Sa thèse décrit comment les contraintes ont guidé ces choix. Cette histoire aide à comprendre pourquoi le navigateur, les liens et les intermédiaires réseau occupent autant de place dans REST.

Fielding a participé aux spécifications de HTTP et des URI, les identifiants des ressources. REST met en relation leurs mécanismes avec les propriétés recherchées : permettre à des composants développés séparément de communiquer et d'évoluer.

Pourquoi REST ne se résume pas à « du JSON sur HTTP »

HTTP définit les échanges sur le réseau : méthodes, statuts et en-têtes. JSON est un format de données. REST décrit l'organisation du système. Une API peut utiliser HTTP et JSON sans respecter toutes les contraintes de REST.

• Du HTTP sans REST. Le RPC (appel de procédure distante) invoque une fonction sur un serveur lointain comme si elle était locale. Déguisé en requête web, à la manière des services SOAP, il utilise HTTP sans suivre le style.
• Du REST sans JSON. Le Web, l'exemple même du style, sert d'abord du HTML.

Pour comprendre une API, examinez donc aussi les informations autour des données : règles de cache, sens des opérations et liens proposés. Elles déterminent ce qu'un client ou un intermédiaire peut faire sans connaître l'implémentation du serveur.

Les contraintes de REST répondent à des besoins concrets

Chacune retire une liberté et apporte en échange une propriété concrète.

Ces contraintes ont des contreparties. Une requête indépendante doit transporter le contexte nécessaire à son traitement. Le cache nécessite des indications permettant de savoir si une réponse peut être réutilisée. Une interface commune peut être moins optimisée qu'un échange taillé pour un seul client.

La contrainte « sans état » ne signifie pas que le serveur oublie les commandes ou les comptes qu'il stocke. Elle concerne l'état de session nécessaire pour comprendre la demande : le serveur doit pouvoir traiter la requête à partir de ce qu'elle fournit.

Le navigateur illustre la découverte par les liens

Le navigateur y est un client générique : il dialogue avec des milliards de serveurs qu'il n'a jamais rencontrés, sans être recompilé pour aucun. C'est possible parce que chaque réponse lui indique ce qu'il peut faire ensuite : les liens à suivre, les formulaires à soumettre.

Le client d'une « API REST » ordinaire, lui, doit connaître l'application à l'avance et écrire les URL en dur dans son code.

L'hypermédia désigne ici les liens et les formulaires présents dans les réponses. Le navigateur sait afficher une page et soumettre un formulaire ; l'utilisateur choisit l'action qui correspond à son objectif. Le serveur fournit les destinations et les contrôles disponibles.

Cette organisation réduit la dépendance aux chemins d'URL connus à l'avance. Elle ne supprime pas tous les contrats : le client doit comprendre le format des messages et le sens des relations qu'il utilise.

Je commencerais la lecture d'une API par une réponse réelle : indique-t-elle ses règles de cache, ses liens et les actions disponibles ? L'article sur l'interface uniforme et l'hypermédia montre comment ces informations guident un client.

Quelques repères sur l’évolution du terme REST

Le sens du mot s'est rétréci à mesure qu'il se répandait. L'expression circule dès 2002-2003 : Amazon appelle déjà « REST » l'interface en paramètres d'URL qu'il offre à côté de SOAP, et Tim O'Reilly rapporte alors que 85 % de l'usage passe par elle. Mais c'est à partir de 2007 qu'elle devient le mot par défaut, et une vulgarisation qui ne retient que les ressources et les verbes.

Sources

• R. T. Fielding, Architectural Styles and the Design of Network-based Software Architectures, thèse, UC Irvine, 2000 — chapitre 5.
• R. T. Fielding, REST APIs must be hypertext-driven, 2008.
• RFC 9110, HTTP Semantics, 2022.
• M. Fowler, Richardson Maturity Model, 18 mars 2010.
• L. Richardson (QCon, 20 novembre 2008).
• L. Richardson & S. Ruby, RESTful Web Services, O'Reilly, 2007.