# Agence immobilière : pourquoi JSON:API plutôt qu’une REST classique

> Définition de la spécification JSON:API et de son intérêt pour un catalogue de biens immobiliers consommé par plusieurs fronts, avec ses limites concrètes.

- Auteur : WordPress Développement
- Publié le : 2023-07-28
- Mis à jour le : 2023-07-28
- Catégorie : Headless & API
- URL : https://www.wpmoderne.fr/headless/agence-immobiliere-json-api-plutot-que-rest/

## L’essentiel

- JSON:API impose un format de réponse standardisé avec relations explicites
- Le catalogue était consommé par un site web et une application mobile distincts
- La limite est apparue sur les requêtes très imbriquées entre biens et agences

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/`.

> L'essentiel à retenir : JSON:API impose un format de réponse standardisé avec relations explicites ; Le catalogue était consommé par un site web et une application mobile distincts ; La limite est apparue sur les requêtes très imbriquées entre biens et agences

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.