Principes REST : ressources, URI et contraintes

REST (Representational State Transfer) est un style d'architecture pour les applications en réseau : le serveur expose des ressources identifiées par des URI, et le client les manipule en échangeant des représentations (un document JSON, par exemple) avec les méthodes standard de HTTP. Une API qui respecte ses contraintes est dite RESTful. Ce chapitre présente les six contraintes de Roy Fielding, le modèle de maturité de Richardson, les règles pour nommer les URI et la façon de traiter les actions qui ne sont pas de simples lectures ou écritures.

Ressource et représentation

Une ressource est tout ce qui mérite un nom dans ton application : un visiteur, une fiche de frais, la liste des fiches d'octobre, un justificatif, et même un concept comme « le profil de l'utilisateur connecté ». Elle a une identité stable, son URI : /v1/fiches/12.

Une représentation est l'état de la ressource à un instant donné, dans un format donné. La fiche 12 peut être représentée en JSON pour le front, en PDF pour l'impression, en CSV pour un export comptable. Le client ne manipule jamais la ressource elle-même (une ligne de la base, un objet en mémoire) : il reçoit une représentation avec GET, et en envoie une pour la créer ou la modifier avec POST, PUT ou PATCH. D'où le nom : transfert d'état par représentation.

Les six contraintes de Fielding

Dans sa thèse de 2000, Roy Fielding définit REST par six contraintes. Une API qui les respecte toutes gagne en simplicité, en performance et en capacité à grandir.

L'interface uniforme est la contrainte qui distingue REST des autres styles. Elle se décompose en quatre règles :

1. Identification des ressources : chaque ressource a son URI.
2. Manipulation par les représentations : le client modifie une ressource en envoyant une représentation (le JSON de la fiche), pas en appelant une fonction.
3. Messages autodescriptifs : chaque message dit comment le lire (la méthode, le Content-Type, le code de statut), sans connaissance cachée.
4. L'hypermédia comme moteur de l'état de l'application (HATEOAS, Hypermedia As The Engine Of Application State) : les réponses contiennent des liens vers les actions possibles, comme une page web contient des liens.

Le modèle de maturité de Richardson

Leonard Richardson a proposé une échelle en quatre niveaux pour situer une API par rapport à REST. Elle est pratique pour analyser une API existante.

La grande majorité des API professionnelles sont au niveau 2. C'est la cible de ton projet de BTS : des ressources bien nommées, les bonnes méthodes, les bons codes de statut.

Voici à quoi ressemble une réponse de niveau 3 : le serveur annonce les actions permises dans l'état actuel de la fiche, et le client n'a pas à coder la règle « on ne clôture qu'une fiche en cours ».

{
  "id": 12,
  "mois": "2026-10",
  "etat": "CR",
  "_links": {
    "self": { "href": "/v1/fiches/12" },
    "lignes-forfait": { "href": "/v1/fiches/12/lignes-forfait" },
    "cloturer": { "href": "/v1/fiches/12", "method": "PATCH" }
  }
}

Nommer les URI

Une URI bien choisie se lit comme une phrase et ne change jamais. Les conventions suivantes ne sont pas imposées par une norme, mais tu les retrouveras dans presque toutes les API sérieuses.

1. Des noms, pas des verbes. Le verbe, c'est la méthode HTTP. On écrit DELETE /v1/fiches/12, pas GET /v1/supprimerFiche?id=12.
2. Des noms au pluriel pour les collections, suivis de l'identifiant pour un élément : /v1/fiches et /v1/fiches/12. Reste cohérent dans toute l'API.
3. Des minuscules et des tirets pour séparer les mots : /v1/frais-hors-forfait, pas /v1/FraisHorsForfait ni /v1/frais_hors_forfait. Le chemin d'une URL est sensible à la casse.
4. La hiérarchie pour les relations de composition, sur deux niveaux au plus : /v1/fiches/12/frais-hors-forfait (les frais de la fiche 12). Au-delà, l'URI devient fragile et longue.
5. La chaîne de requête pour filtrer, trier et paginer, pas le chemin : /v1/fiches?etat=CL&mois=2026-10, pas /v1/fiches/cloturees/octobre.
6. Pas d'extension de fichier ni de détail technique : pas de .php, .json, ni de nom de table. Le format se négocie avec Accept, et l'implémentation peut changer.
7. Pas de barre oblique finale : /v1/fiches, pas /v1/fiches/. Choisis une forme et redirige ou refuse l'autre.
8. Des identifiants stables et non devinables si possible : l'identifiant d'une ressource ne doit pas changer, et un UUID (/v1/justificatifs/3f1c9a2e-…) ne permet pas de deviner les ressources voisines comme un entier qui s'incrémente. Ce n'est pas une protection suffisante, mais une défense complémentaire.

Collection et élément : le tableau CRUD

Chaque ressource s'expose en général sous deux formes : la collection (/v1/fiches) et l'élément (/v1/fiches/12). Les opérations CRUD (Create, Read, Update, Delete) se répartissent ainsi :

Les méthodes qui n'ont pas de sens sur une URI renvoient 405 : on ne fait ni PUT ni DELETE sur toute la collection /v1/fiches, ni POST sur un élément /v1/fiches/12 (sauf si l'élément contient lui-même une collection).

Les ressources d'AppliFrais

Partons du besoin. Un visiteur crée une fiche par mois, y saisit des frais forfaitisés (étapes, kilomètres, nuitées, repas) et des frais hors forfait avec leur justificatif, puis la clôture. Un comptable consulte les fiches clôturées, les valide et les met en paiement. Les ressources qui en découlent :

Remarque le choix pour les frais hors forfait : on les crée sous leur fiche (POST /v1/fiches/12/frais-hors-forfait, la relation est claire), mais on les manipule ensuite par leur propre URI, plus courte. Les deux formes coexistent souvent.

Les actions qui ne sont pas du CRUD

Clôturer une fiche, la valider, la mettre en paiement : ce ne sont ni des créations, ni des suppressions. Trois façons de les exposer, de la plus « REST » à la plus pragmatique.

Modifier un attribut d'état. La clôture est un changement de l'attribut etat :

PATCH /v1/fiches/12 HTTP/1.1
Content-Type: application/json

{"etat":"CL"}

L'API vérifie que la transition est permise (CR vers CL, CL vers VA, VA vers MP) et renvoie 409 sinon. C'est simple, mais une seule route porte des règles de droits différentes selon la valeur envoyée : le visiteur peut clôturer, seul le comptable peut valider.

Créer une ressource qui représente l'action. Une validation est un événement qui a une date, un auteur, un montant validé : elle mérite d'être une ressource.

POST /v1/fiches/12/validations HTTP/1.1
Content-Type: application/json

{"montantValide": 389.20, "commentaire": "Repas du 14 refusé : justificatif illisible"}

L'API crée la validation (201), passe la fiche à l'état VA et garde une trace de qui a validé quoi. Les droits sont simples à poser : seuls les comptables peuvent faire POST sur /validations.

Une sous-ressource d'action, avec un verbe. POST /v1/fiches/12/cloture. Ce n'est pas pur, mais c'est lisible, et de nombreuses API publiques le font (GitHub, Stripe). Si tu choisis cette forme, garde POST et réserve-la aux vraies actions métier.

REST face au style RPC

Le style RPC (Remote Procedure Call, appel de procédure distante) expose des fonctions plutôt que des ressources : POST /lireFiche, POST /validerFiche. SOAP, gRPC et JSON-RPC en sont des exemples. Ce n'est pas une erreur en soi : gRPC est un excellent choix entre microservices (chapitre 12). Mais une API qui mélange les deux styles sans le dire est déroutante.

Exercices