Ressources et URI

Chaque chose à sa place, une adresse dans l'ombre

Notion de ressource

Dans REST, tout est ressource.
Un client, une commande, un produit, un fichier, un statut.
Même un calcul, un état éphémère, une recherche.
Si on peut le nommer, on peut en faire une ressource.
Pas des actions, pas des fonctions — des choses.
Des entités froides, identifiables, que le serveur expose et que le client manipule.

URI comme identifiant unique

Chaque ressource a une adresse. Une URI.
https://api.ombre.net/v1/clients/883
https://api.ombre.net/v1/commandes/2024-MAY-17/items
C’est comme un matricule. Unique, permanent, prévisible.
Le client la connaît, l’utilise, la garde en mémoire.
Si l’URI change, le lien est rompu. L’objet disparaît du réseau.

Ressource ≠ action

Une erreur classique : mélanger la ressource et ce qu’on en fait.
En REST, l’action est portée par la méthode HTTP, pas par l’URI.
GET /clients → lire la liste.
POST /clients → en créer un.
DELETE /clients/52 → le supprimer.
L’URI reste stable, c’est le verbe qui change.
Pas de /getClient ou /deleteClient.
Ça évite la confusion. Ça garde les choses propres.

Bonnes pratiques de nommage

• Noms, pas de verbes :
  /clients, /factures, /stocks — pas /getClients.
• Pluriel pour les collections :
  /clients pour la liste, /clients/52 pour un élément.
• Hiérarchie logique :
  /clients/52/commandes — les commandes du client 52.
  /clients/52/commandes/101/items — les articles de la commande 101.
  La structure raconte la relation.
• Snake_case ou kebab-case, mais pas de CamelCase dans les URI :
  /bons-de-commande, /états_paiement.
  REST préfère le kebab-case, lisible et universel.
• Stabilité : une URI définie ne change plus.
  Si la ressource bouge, on utilise une redirection 301.
  On ne brise pas les liens.

Différence entre ressource et représentation

La ressource est l’entité abstraite, côté serveur.
La représentation est la forme sous laquelle elle voyage.
JSON, XML, HTML, PDF — autant de façons de montrer la même chose.
Le client demande une représentation avec l’en-tête Accept.
Le serveur choisit et répond avec Content-Type.
La ressource reste unique. Ses visages sont multiples.

Une API REST bien conçue, c’est une carte d’identités.
Chaque ressource a son adresse, son statut, ses représentations.
Le client navigue, consulte, modifie — sans jamais voir le système derrière.
Juste des URI, des méthodes, et du JSON qui circule dans la nuit.