🌐 API REST – Le Guide Ultime

REST signifie REpresentational State Transfer. C'est un style d'architecture (un ensemble de règles/principes), *pas* un protocole ou un standard (contrairement à SOAP). Il a été défini par Roy Fielding dans sa thèse en 2000.

L'idée de base est de traiter le serveur comme une collection de "Ressources" (des "Noms", ex: un utilisateur, un produit) que l'on peut manipuler en utilisant les verbes HTTP (des "Verbes", ex: GET, POST) standards.

RPC vs REST (Le changement de mentalité)

Avant REST, les APIs étaient souvent "RPC" (Remote Procedure Call). On appelait des *fonctions* sur le serveur.

POST /api/getUser.php?id=123
POST /api/createNewUser
POST /api/updateUser?id=123

GET    /api/users/123
POST   /api/users
PUT    /api/users/123

Une API "RESTful" est une API qui respecte les 6 contraintes de REST (voir 2.1).

Une API n'est "RESTful" que si elle respecte 6 contraintes architecturales. (En pratique, beaucoup d'APIs "REST" ne respectent pas la #4 et la #6).

Avant REST, SOAP (Simple Object Access Protocol) était le standard (surtout dans le monde Java et .NET). C'est un *protocole* lourd et rigide.

POST /users
Content-Type: application/json

{
  "name": "Jean"
}

POST /UserService
Content-Type: application/soap+xml

<?xml version="1.0"?>
<soap:Envelope ...>
  <soap:Body>
    <m:CreateUser>
      <m:Name>Jean</m:Name>
    </m:CreateUser>
  </soap:Body>
</soap:Envelope>

GraphQL est le "challenger" moderne de REST. Il ne remplace pas REST, mais résout certains de ses problèmes, notamment le "Over/Under-fetching".

Exemple : Le Problème du Dashboard

Objectif : Afficher le nom de l'utilisateur, et les titres de ses 3 derniers articles.

/* Appel 1: */
GET /api/me
<-- { "id": 1, "name": "Jean", "email": "..." }

/* Appel 2 (après avoir eu l'ID): */
GET /api/users/1/posts?limit=3
<-- [
  { "id": 10, "title": "Titre 1", ... },
  { "id": 11, "title": "Titre 2", ... }
]

/* Appel 1 (POST /graphql): */
query {
  me {
    name
    posts(limit: 3) {
      title
    }
  }
}
/* Réponse unique : */
<-- {
  "data": {
    "me": {
      "name": "Jean",
      "posts": [ { "title": "Titre 1" }, ... ]
    }
  }
}

En REST, les URIs (Uniform Resource Identifiers) identifient les **Ressources** (les "Noms"). Elles ne doivent **jamais** contenir de verbes (actions).

Bon vs Mauvais Design d'URI

Collections vs Éléments

• Collection : (ex: /posts) - La liste de *tous* les articles.
• Élément : (ex: /posts/123) - Un article *spécifique*.

Ressources Imbriquées (Nested)

Pour exprimer des relations (Parent/Enfant).

/* Récupérer TOUS les commentaires */
GET /comments

/* Récupérer TOUS les commentaires de l'article 123 */
GET /posts/123/comments

/* Récupérer LE commentaire 456 de l'article 123 */
GET /posts/123/comments/456

Filtrage (Query Parameters)

Pour filtrer, trier ou paginer une *collection*, on utilise les "query string params" (?).

/* Récupérer les articles publiés, triés par date */
GET /posts?status=published&sort=date_desc

/* Récupérer la page 2 (10 articles par page) */
GET /posts?page=2&limit=10

Les verbes HTTP sont les "actions" que l'on applique aux "ressources" (URIs). Le mapping CRUD (Create, Read, Update, Delete) est le fondement de REST.

Les 5 Verbes Principaux

PUT vs PATCH (Une distinction importante)

/* Donnée actuelle sur le serveur:
{ "id": 123, "name": "Jean", "job": "Dev" }
*/

/* Requête (on oublie "job"): */
PUT /users/123
{
  "name": "Nouveau Jean"
}

/* Résultat (le "job" est effacé !):
{ "id": 123, "name": "Nouveau Jean" }
*/

/* Donnée actuelle sur le serveur:
{ "id": 123, "name": "Jean", "job": "Dev" }
*/

/* Requête (on ne change que "name"): */
PATCH /users/123
{
  "name": "Nouveau Jean"
}

/* Résultat (le "job" est préservé):
{ "id": 123, "name": "Nouveau Jean", "job": "Dev" }
*/

Le client (navigateur, app) a besoin de savoir si l'opération a réussi, échoué, ou pourquoi. Le code de statut HTTP est la réponse standardisée du serveur.

Les 5 Classes de Codes

• 1xx (Information) : "J'ai reçu, je continue..." (Rare en REST).
• 2xx (Succès) : "OK, j'ai fait ce que tu as demandé."
• 3xx (Redirection) : "Va voir ailleurs."
• 4xx (Erreur Client) : "Tu as fait une erreur." (ex: 404 Not Found)
• 5xx (Erreur Serveur) : "J'ai fait une erreur." (ex: 500 Internal Error)

Les Codes Incontournables

Le "R" de REST (Representational) signifie que le client n'interagit jamais avec la "vraie" ressource (ex: la ligne en BDD), mais avec une représentation de celle-ci (JSON, XML, ...).

Bien que REST soit agnostique (il peut utiliser XML, YAML, ou même du texte), le JSON (JavaScript Object Notation) est devenu le standard *de facto* pour 99% des APIs REST.

Pourquoi JSON ?

• Léger : Beaucoup moins verbeux que le XML (pas de balises fermantes).
• Natif pour JavaScript : Le format JSON est la syntaxe littérale d'un objet JavaScript. JSON.parse() et JSON.stringify() sont tout ce dont on a besoin.
• Lisible par l'humain : Facile à lire et à débugger.

L'importance du Content-Type

Les messages REST doivent être "auto-descriptifs". L'en-tête (header) HTTP Content-Type est crucial.

Exemple : Requête (Client -> Serveur)

POST /api/users
Host: api.example.com
Content-Type: application/json  /* <-- Je préviens le serveur: "Je t'envoie du JSON" */
Accept: application/json        /* <-- Je préviens le serveur: "J'aimerais une réponse en JSON" */

{
  "username": "jean",
  "email": "jean@mail.com"
}

Exemple : Réponse (Serveur -> Client)

HTTP/1.1 201 Created
Content-Type: application/json  /* <-- Le serveur confirme: "Je te réponds en JSON" */
Location: /api/users/124

{
  "id": 124,
  "username": "jean",
  "email": "jean@mail.com",
  "createdAt": "2025-11-06T16:30:00Z"
}

C'est la contrainte la plus importante et la plus structurante de REST. "Stateless" = Sans état.

Cela signifie que le **serveur** n'a pas le droit de stocker d'information sur la "session" du client. Chaque requête du client doit contenir *toute* l'information (y compris l'authentification) pour que le serveur puisse la traiter de manière autonome.

Une opération (un verbe HTTP) est idempotente si l'appeler une fois a *exactement* le même effet sur l'état du serveur que l'appeler 100 fois.

Pourquoi c'est important ? Les "retries" (ré-essais). Si une app mobile envoie une requête et subit une coupure réseau (elle ne reçoit jamais la réponse), peut-elle renvoyer la requête sans risque ?

Le Problème : Votre API v1 est utilisée par une app mobile. Vous devez faire un "breaking change" (ex: renommer le champ "name" en "firstName" et "lastName"). Comment faire sans casser l'ancienne app mobile (v1) ?

Vous devez introduire une v2. Il y a 3 façons de faire.

L'Approche "Additive" (No-Version)

La meilleure solution est... de ne pas versionner.

• Ne jamais faire de "Breaking Change".
• (v1) Réponse : { "name": "Jean Dupont" }.
• (v2) Vous voulez changer ? Ajoutez des champs, ne supprimez/renommez rien.
• (v2) Réponse : { "name": "Jean Dupont", "firstName": "Jean", "lastName": "Dupont" }.
• L'ancienne app (v1) ne lira que name. La nouvelle app (v2) lira firstName et lastName. Tout le monde est content.

1. HATEOAS (Le "H" de REST)

Hypermedia As The Engine Of Application State. C'est la contrainte la plus pure de REST, et celle que 99% des APIs ignorent.

L'idée : Le client ne devrait *jamais* avoir à "construire" des URLs. La réponse de l'API doit contenir les *actions* (liens) possibles.

Exemple : GET /users/123 (avec HATEOAS)

{
  "id": 123,
  "name": "Jean",
  "job": "Dev",
  
  /* HATEOAS: Le serveur dit au client ce qu'il peut faire ensuite */
  "_links": {
    "self": {
      "href": "/users/123",
      "method": "GET"
    },
    "posts": {
      "href": "/users/123/posts",
      "method": "GET"
    },
    "update": {
      "href": "/users/123",
      "method": "PUT"
    },
    "delete": {
      "href": "/users/123",
      "method": "DELETE"
    }
  }
}

2. Outils (L'écosystème)

Références Extérieures (Liens)