Embed and Fields

Embed and Fields

Two WordPress query parameters that reduce requests and payload size.

• _embed includes related resources (author, featured image, terms, replies) inside each item, so you do not fetch them one by one.
• _fields limits the response to the properties you need.

Both are available on every fluent query as withEmbed and withFields, and on typed requests through their extra query parameters.

final res = await client.posts.query
    .withEmbed(['author', 'wp:featuredmedia'])   // no arguments embeds everything
    .withFields(['id', 'title', 'link', '_embedded', '_links'])
    .execute();

final post = res.dataOrThrow().first;
final e = post.embedded;                          // Embedded view of post._embedded
print(e.author?.name);
print(e.featuredMedia?.sourceUrl);
print(e.categories.map((c) => c.name));
print(e.terms('post_tag'));                       // any taxonomy
print(e.isPresent);                               // false if nothing was embedded

The typed view embedded exists on every response model (ISelfRespresentive). Accessors return null or an empty list when the relation was not embedded, and ignore relations WordPress answered with an error (for example a hidden author). When using withFields, keep _embedded (and _links) in the list or the embedded data is stripped.

Without the fluent API

final r = await client.posts.list(ListPostRequest(
  extra: {'_embed': 'author,wp:featuredmedia', '_fields': 'id,title,_embedded'},
));
final post = r.dataOrThrow().first;
print(post.embedded.author?.name);

Model helpers use it

post.getMedia(client) and post.getAuthor(client) read the embedded data when it is present and only call the API when it is not (Interfaces and Extensions).

Accessors

Accessor	Returns
author	User?
featuredMedia	Media?
categories, tags	List<Category> / List<Tag>
replies	List<Comment>
terms(taxonomy)	Raw maps of the embedded terms of any taxonomy (category, post_tag, a custom one)
items(relation)	Raw maps for any link relation, for example wp:attachment
up	The parent resource as a raw map
isPresent	Whether _embedded was in the payload at all

Embedded items are parsed tolerantly: partial objects (as returned in the embed context) are accepted, and relations WordPress answered with an error are skipped.