Les masques que portent les ressources
Formats de représentation
Une ressource est une entité abstraite, silencieuse, côté serveur.
Pour voyager, elle prend une forme.
Deux formats dominent l’ombre des APIs modernes :
-
JSON – JavaScript Object Notation.
Léger, lisible, natif pour le web.
Un objet, des paires clé–valeur, des tableaux.
Du texte brut, structuré.
{ "id": 52, "nom": "Marin", "actif": true } -
XML – eXtensible Markup Language.
Plus lourd, plus verbeux, mais structuré, normé, puissant.
Balises, attributs, schémas.
Encore présent dans certains milieux — banque, santé, systèmes anciens.
<client><id>52</id><nom>Marin</nom><actif>true</actif></client>
D’autres formats existent : YAML, MessagePack, protobuf.
Mais en REST, JSON règne. Simple, universel, efficace.
Notion de Content-Type
Chaque représentation est annoncée.
Dans la requête, le client précise ce qu’il accepte :
Accept: application/json
Accept: application/xml
Dans la réponse, le serveur indique ce qu’il envoie :
Content-Type: application/json
Content-Type: application/xml; charset=utf-8
C’est un contrat de lecture.
Si le client demande du JSON mais reçoit du XML, c’est un conflit.
Le Content-Type est la carte d’identité du format. Sans lui, le corps n’est qu’un tas d’octets ambigus.
Sérialisation et désérialisation
- Sérialisation : transformer un objet métier (en mémoire) en flux JSON/XML.
Le serveur le fait avant d’envoyer. - Désérialisation : repartir du flux reçu pour reconstruire l’objet côté client.
Deux opérations miroirs.
Si le format change, il faut que les deux côtés s’accordent.
Un champ manquant, un type différent, et la désérialisation échoue.
Silencieusement, parfois.
Indépendance entre ressource et format
C’est un principe fondamental.
La ressource n’est pas sa représentation.
Un client /clients/52 peut renvoyer du JSON, du XML, du CSV, même du PDF selon ce que le client accepte.
La même ressource, plusieurs visages.
Le serveur stocke la donnée brute — en base, en mémoire.
Il la transforme à la demande selon le Accept du client.
Ça permet :
- D’ajouter des formats sans toucher à la logique métier.
- De servir des clients variés (web, mobile, partenaire) avec les représentations qu’ils préfèrent.
- D’évoluer sans casser les clients existants.
Mais il faut garder la cohérence :
Les mêmes champs, les mêmes règles de validation, quel que soit le format.
La ressource est unique. Ses représentations sont multiples, mais fidèles.
Dans une API REST, on n’échange jamais la ressource elle-même.
Seulement son reflet, son ombre portée dans un format négocié.
Le Content-Type est la clé.
La sérialisation, le pont.
Et derrière, la ressource reste intacte, silencieuse, indifférente au format qui la représente.