« Une réponse REST peut inclure des données intégrées pour les ressources liées », précise la documentation officielle de l’API REST de WordPress à propos du paramètre _embed. La phrase est courte, mais elle décrit un mécanisme interne assez élaboré, construit autour des liens hypermédia que chaque réponse contient déjà, qu’on utilise ou non ce paramètre.
La base : des liens présents dans toute réponse
Avant même de parler d’embed, il faut comprendre que chaque réponse de l’API REST de WordPress contient une section _links, générée automatiquement par le contrôleur concerné via la méthode prepare_links(). Cette section décrit les relations d’une ressource sous forme d’URL relatives à l’API : le lien vers l’auteur d’un article, vers sa collection d’appartenance, vers sa pièce jointe mise en avant, vers ses termes de taxonomie. Ces liens suivent la spécification HAL, un format de description hypermédia utilisé par de nombreuses API REST au-delà de WordPress.
Sans _embed, ces liens restent de simples chaînes de caractères que le client devrait suivre lui-même via des requêtes supplémentaires. C’est là qu’intervient le mécanisme de résolution interne.
Le mécanisme de résolution
Quand une requête contient le paramètre _embed, la classe WP_REST_Server, après avoir construit la réponse normale d’un contrôleur, appelle sa méthode response_to_data() avec l’option d’embarquement activée. Cette méthode parcourt la section _links déjà construite, et pour chaque relation éligible à l’embarquement, effectue une requête interne — pas une requête HTTP réelle, mais un appel direct au serveur REST via WP_REST_Server::dispatch() sur la route correspondante.
Le résultat de chacune de ces requêtes internes est placé dans une nouvelle section _embedded, avec une clé qui reprend le nom de la relation d’origine (author, wp:featuredmedia, wp:term, replies…). Ce mécanisme évite une vraie requête HTTP aller-retour pour chaque relation : tout se joue en interne, dans le même cycle de traitement PHP que la requête d’origine, ce qui explique pourquoi l’embarquement de plusieurs relations reste relativement peu coûteux comparé à autant de requêtes HTTP séparées depuis le client.
Pourquoi la résolution s’arrête à un niveau
Ce mécanisme de requête interne pourrait, en théorie, se répéter récursivement : l’auteur embarqué pourrait lui-même embarquer ses propres relations, qui pourraient à leur tour en embarquer d’autres. WordPress ne le fait volontairement pas. La résolution s’arrête à un seul niveau de profondeur, ce qui évite un risque réel d’explosion combinatoire de requêtes internes sur un contenu aux relations nombreuses — un article avec plusieurs auteurs, chacun avec plusieurs rôles, chacun lié à plusieurs autres contenus.
Cette limite volontaire explique pourquoi un front qui a besoin d’une relation de second niveau — par exemple l’auteur d’un commentaire posté sur un article déjà embarqué — doit composer plusieurs appels distincts, ou construire un point de terminaison personnalisé qui agrège lui-même ce que l’embed natif ne peut pas fournir en une seule passe.
Un cas particulier : les erreurs d’embarquement
Quand la résolution interne d’une relation échoue — une pièce jointe supprimée, un utilisateur sans droit d’accès à la ressource liée depuis le contexte de la requête — WordPress n’omet pas simplement la clé correspondante. Il inclut à sa place une structure décrivant l’échec, généralement sous forme d’un objet contenant un code d’erreur. C’est un point souvent négligé côté front : un tableau _embedded présent ne garantit pas que chacune de ses entrées contient la ressource attendue plutôt qu’une description d’erreur.
Ce que ça change en pratique
- Comprendre que l’embed s’appuie sur les mêmes contrôleurs REST que les requêtes classiques, pas sur un raccourci parallèle
- Ne jamais présumer qu’une relation embarquée soit forcément résolue avec succès
- Se rappeler que la résolution ne descend jamais à plus d’un niveau, quelle que soit la complexité du graphe de contenu
En résumé
Le mécanisme derrière _embed repose sur une idée simple mais bien construite : réutiliser la section _links déjà présente dans chaque réponse, et suivre ces liens via des appels internes au serveur REST plutôt que via de vraies requêtes HTTP. Cette architecture explique à la fois son efficacité — un seul cycle de traitement pour plusieurs relations — et sa limite volontaire à un seul niveau de profondeur, pensée pour éviter qu’une simple requête ne déclenche une cascade incontrôlée de résolutions internes.
