GET /wp-json/wp/v2/posts/42?_embed : cette seule ligne remplace, à elle seule, trois appels réseau que beaucoup de projets headless effectuent encore sans le savoir. Le front récupère l’article, puis interroge /wp/v2/users/{id} pour l’auteur, puis /wp/v2/media/{id} pour l’image mise en avant. Trois allers-retours, trois temps de latence cumulés, pour un contenu que l’API pouvait livrer d’un coup.
Le paramètre _embed existe depuis longtemps dans l’API REST de WordPress et reste pourtant sous-utilisé. Il s’appuie sur le mécanisme des liens hypermédia déjà présents dans chaque réponse, sous la clé _links, pour aller chercher les ressources associées et les inclure directement dans le corps de la réponse, sous une nouvelle clé _embedded.
Ce que fait réellement _embed
Chaque réponse de l’API REST contient déjà une section _links qui décrit les relations d’une ressource : son auteur, sa collection d’appartenance, sa révision, sa pièce jointe mise en avant, ses termes de taxonomie. Ces liens ne sont que des URL ; encore faut-il les suivre pour obtenir les données. C’est exactement ce que fait _embed : il indique au serveur de résoudre lui-même ces relations avant de renvoyer la réponse, plutôt que de laisser le client s’en charger.
Concrètement, ajouter ?_embed à une requête sur un article transforme la réponse : la clé _embedded.author contient l’objet utilisateur complet, _embedded["wp:featuredmedia"] contient l’objet média avec ses tailles d’image, et _embedded["wp:term"] contient les taxonomies associées. Le front n’a plus qu’à lire ces clés, sans lancer la moindre requête supplémentaire.
Limiter l’embed à ce qui est utile
Tout embarquer n’est pas toujours souhaitable. Sur une liste de vingt articles, embarquer systématiquement l’auteur, le média et les termes peut alourdir sensiblement la réponse JSON, surtout si les images comportent de nombreuses tailles enregistrées. Depuis les versions récentes de l’API, il est possible de cibler l’embed avec _embed=wp:featuredmedia pour ne récupérer que la ressource voulue, sans les autres relations.
- Sur une page de liste, privilégier l’embed ciblé pour ne pas gonfler la charge utile
- Sur une page de détail, l’embed complet reste souvent le plus simple à exploiter
- Combiner avec
_fieldspour ne garder que les propriétés réellement affichées
Un exemple de requête et de réponse
Voici la forme d’une requête typique côté front, suivie d’un extrait de la structure obtenue :
fetch('https://exemple.test/wp-json/wp/v2/posts/42?_embed=author,wp:featuredmedia')
.then(res => res.json())
.then(post => {
const auteur = post._embedded.author[0].name;
const image = post._embedded['wp:featuredmedia'][0].source_url;
console.log(auteur, image);
});
La réponse conserve la structure habituelle de l’article, mais ajoute la clé _embedded en plus de _links. Les deux tableaux (author et wp:featuredmedia) contiennent chacun un seul élément dans le cas d’un article classique, ce qui explique l’indexation [0] presque systématique dans les exemples de code qu’on trouve sur le sujet.
Les pièges à connaître
L’embed ne résout pas les liens en cascade au-delà d’un niveau : un article embarque son auteur, mais l’auteur embarqué n’embarque pas à son tour ses propres relations. Pour un front qui a besoin d’informations profondément imbriquées (l’auteur d’un commentaire sur un article, par exemple), il faudra composer plusieurs appels ou construire un point de terminaison personnalisé qui agrège ce qui est nécessaire.
Autre piège fréquent : si la pièce jointe mise en avant a été supprimée ou son accès restreint, la clé wp:featuredmedia peut renvoyer un tableau contenant un objet d’erreur plutôt que le média attendu. Un front qui suppose aveuglément la présence de source_url plantera sur ce cas limite ; mieux vaut toujours vérifier la présence de la clé avant de l’utiliser dans le rendu.
En résumé
Le paramètre _embed est l’un des outils les plus rentables de l’API REST pour un front découplé : il transforme trois requêtes en une seule, réduit la latence perçue et simplifie le code côté client. Bien dosé — en ciblant les relations réellement affichées plutôt qu’en embarquant tout par défaut — il reste l’un des premiers réflexes à adopter avant d’aller chercher des solutions plus lourdes comme un point de terminaison personnalisé ou une couche GraphQL.
