Une spécification unique pour la façon dont un client doit demander que des ressources soient récupérées ou modifiées, et pour la façon dont un serveur doit répondre à ces demandes : c’est ainsi que la documentation officielle de la spécification résume l’intérêt de JSON:API. Non pas un remplacement de REST, mais une convention stricte sur la forme des réponses REST elles-mêmes. Cette distinction a été centrale dans le choix fait pour un réseau d’agences immobilières indépendantes partageant un même catalogue de biens.
Le catalogue devait être consommé par deux fronts distincts et développés par deux équipes différentes : un site web grand public en Nuxt, et une application mobile destinée aux mandataires pour la gestion de leurs visites. Sans convention commune, chaque équipe aurait fini par interpréter différemment la structure des réponses de l’API REST par défaut de WordPress, avec un risque réel de divergence au fil des évolutions.
Ce que JSON:API impose réellement
La spécification définit un format de réponse précis : chaque ressource possède un type et un id, ses attributs sont regroupés sous une clé attributes, et ses relations vers d’autres ressources sont explicitement déclarées sous une clé relationships, avec la possibilité de les inclure directement dans la réponse via le paramètre include. Cette structure élimine l’ambiguïté qui existe parfois dans l’API REST native de WordPress, où la présence ou l’absence d’un champ embarqué dépend de choix d’implémentation propres à chaque projet.
{
"data": {
"type": "bien",
"id": "482",
"attributes": {
"titre": "Maison de ville avec jardin",
"prix": 285000
},
"relationships": {
"agence": {
"data": { "type": "agence", "id": "12" }
},
"mandataire": {
"data": { "type": "mandataire", "id": "37" }
}
}
},
"included": [
{ "type": "agence", "id": "12", "attributes": { "nom": "Agence du Marché" } }
]
}Fonctionnement en pratique sur WordPress
WordPress ne génère pas nativement des réponses conformes à JSON:API : il a fallu construire une couche intermédiaire, sous la forme d’un espace de noms REST dédié (immo-jsonapi/v1), qui transforme les objets WP_Post et leurs relations en respectant strictement le format attendu par la spécification, plutôt que le format par défaut de /wp/v2/.
Quatre types de relations ont été modélisées de cette façon : un bien appartient à une agence, il est suivi par un mandataire, il peut faire l’objet de plusieurs visites planifiées, et chaque visite est liée à un contact prospect. Standardiser ces quatre relations selon la même convention a permis aux deux équipes front de développer leurs vues indépendamment, chacune sachant exactement où trouver un identifiant de relation dans la réponse, sans avoir à se concerter à chaque nouvelle fonctionnalité.
Ce que ce choix a apporté concrètement
- Une seule documentation d’API à maintenir, valable pour les deux fronts
- Un typage plus simple à générer côté TypeScript, la structure étant prévisible
- Moins de requêtes redondantes grâce au paramètre
include, qui évite d’appeler séparément l’agence de chaque bien affiché dans une liste
Les limites rencontrées
La rigueur de JSON:API a aussi montré ses limites sur les requêtes très imbriquées, en particulier lorsque l’application mobile des mandataires avait besoin d’afficher, en une seule requête, un bien avec son agence, son mandataire et l’historique complet de ses visites incluant leurs contacts respectifs. La profondeur d’inclusion nécessaire alourdissait sensiblement la réponse, et il a fallu introduire une pagination spécifique sur le tableau included pour éviter des réponses démesurées.
Une spécification standardisée n’élimine pas la réflexion sur la performance, elle la déplace simplement vers un autre endroit : au lieu de discuter du format, on discute de la profondeur des relations à charger d’un coup.
Ce que cet article ne couvre pas
GraphQL n’a volontairement pas été retenu comme option de comparaison ici, bien qu’il réponde à un besoin voisin de relations explicites entre ressources. Le choix s’est porté sur JSON:API précisément parce que la spécification reste plus proche de REST, ce qui a permis de conserver une bonne partie de l’infrastructure REST existante plutôt que d’introduire un tout nouveau moteur de requêtes.
Notre verdict
JSON:API a rempli son rôle de convention partagée entre deux équipes front qui n’avaient pas à se coordonner en continu pour interpréter les réponses de l’API. La discipline qu’elle impose a un coût de mise en place initial réel, mais ce coût s’est amorti rapidement dès que le nombre de types de ressources et de relations à exposer a dépassé une poignée d’entités simples.
