Media / Attachments REST API endpoint: Include post (i.e. attached parent) as an embeddable link in the response

[andrewserong]

In the Media / Attachments REST API endpoint, can we include the post (i.e. attached parent or "uploaded to") in the response, as a link under _links?

The goal here is to make it easier to display or work with the "uploaded to" / "attached to" field of media via the REST API endpoint, as part of exploring a new media library.

In my explorations so far, it will be a fair bit easier to work with if we can include a link in the API response to the post that the media item is associated with, as we'd then be able to query the endpoint with _embed: 'post' to list out the post title that media is linked to.

For context, the new media library is being proposed in ​https://github.com/WordPress/gutenberg/issues/55238, where an Attached to / Uploaded to field will be required.

Update: the final shape of this link relation is https://api.w.org/attached-to.

In the attachments controller (i.e. for the media endpoint) add post to the links in the API response, that provides a link to the API call to get the linked post — i.e. the parent, or the post that the media item is attached to.

The purpose is to make it easier to fetch linked posts or pages that media items are attached to, via the REST API. This is part of some of the work I've been exploring for the new media library (proposed in ​https://github.com/WordPress/gutenberg/issues/55238). When listing (or providing UI to make changes to) the "uploaded to" field (or "attached to" or whatever it should be called), it'll be easier to do so if we can embed the post in the API response for media items.

Trac ticket: https://core.trac.wordpress.org/ticket/64034

@rmccue and @spacedmonkey just adding you as reviewers for this one as I know you've both done a lot of REST API work in the past. I've had a bit of a break from contributing directly to core this year, so apologies for the ping if you're not the right folks to ping on these sorts of PRs (and of course let me know if there's anyone else I should request a review from). Thanks!

Thanks for the review! I'll just ping another couple of folks for visibility in case anyone else has opinions on the shape of this change. FYI: @swissspidy and @adamsilverstein in case this touches upon any media stuff y'all are working on.

Thanks everyone! I'll look to commit this today

[andrewserong]

In 60893:

REST API: Add an embeddable post to the media endpoint within links

Allows consumers to more easily fetch details of the post a media item is linked to, i.e. to more easily display the uploaded to / attached to status of media items.

Props andrewserong, ramonopoly, mukesh27, adamsilverstein.
Fixes #64034.

[TimothyBlynJacobs]

post is not a valid IANA link relation, the relation either needs to be one of the registered relations or be an api.w.org URL. ​https://www.iana.org/assignments/link-relations/link-relations.xhtml

There is an up link that points to the parent, but it is only included when the post type is hierarchical right now.

[andrewserong]

Thanks @TimothyBlynJacobs, that's good to know! I think using a api.w.org URL likely makes the most sense as media attachment -> post isn't necessarily a hierarchical relationship in the way that, say, pages and page parents are. I'll put up a PR to try out ​https://api.w.org/post as the relation.

This PR updates the post link within the REST API media attachment response to use the https://api.w.org/ prefix, as post isn't a valid IANA link relation: ​https://www.iana.org/assignments/link-relations/link-relations.xhtml

Kudos @TimothyBJacobs for catching this.

### Testing instructions

These are basically the same testing instructions as in ​https://github.com/WordPress/wordpress-develop/pull/10027:

If you'd like to test this from within the block editor:

1. Open up the media library and upload an image.
2. From the list view within the media library, click Attach under the Uploaded To column and attach the media items to a post
3. Make a note of the id of your images (i.e. grab it from the url)
4. Open the block editor, and try running the following from your browser console (note you might have to run these commands twice as the first call will return undefined as the request hasn't been resolved yet):

// Replace 27 with the id of an image that is attached to a post — you should see `wp:post` in the list of `_links`
wp.data.select( 'core' ).getEntityRecord( 'postType', 'attachment', 27 );
// Again, replace 27 with the id of an image that is attached to a post — in this call, you should see the `wp:post` under `_embedded` in the response
wp.data.select( 'core' ).getEntityRecord( 'postType', 'attachment', 27, { _embed: 'wp:post' } );

Trac ticket: https://core.trac.wordpress.org/ticket/64034

This PR updates the post link within the REST API media attachment response to use the https://api.w.org/ prefix, as post isn't a valid IANA link relation: ​https://www.iana.org/assignments/link-relations/link-relations.xhtml

Kudos @TimothyBJacobs for catching this.

### Testing instructions

These are basically the same testing instructions as in ​https://github.com/WordPress/wordpress-develop/pull/10027:

If you'd like to test this from within the block editor:

1. Open up the media library and upload an image.
2. From the list view within the media library, click Attach under the Uploaded To column and attach the media items to a post
3. Make a note of the id of your images (i.e. grab it from the url)
4. Open the block editor, and try running the following from your browser console (note you might have to run these commands twice as the first call will return undefined as the request hasn't been resolved yet):

// Replace 27 with the id of an image that is attached to a post — you should see `wp:post` in the list of `_links`
wp.data.select( 'core' ).getEntityRecord( 'postType', 'attachment', 27 );
// Again, replace 27 with the id of an image that is attached to a post — in this call, you should see the `wp:post` under `_embedded` in the response
wp.data.select( 'core' ).getEntityRecord( 'postType', 'attachment', 27, { _embed: 'wp:post' } );

Trac ticket: https://core.trac.wordpress.org/ticket/64034

[TimothyBlynJacobs]

I don't think post is necessarily what we want here. The link relation should really describe the relationship between the two entities. I'd consider something like featuredin as a counter part to featuredmedia.

[andrewserong]

@TimothyBlynJacobs I went with post because it's already part of the API schema for this endpoint (post — The ID for the associated post of the attachment) so that the link matches (or is connected to) the key within each response object.

I notice with a couple of the other api.w.org prefixes used elsewhere we're also using nouns (e.g. ​https://api.w.org/term and ​https://api.w.org/attachment) so this feels a bit more consistent to me than featuredin.

[TimothyBlynJacobs]

For sure, but those are cases where we need to be more generic. Notably, we don't already have an post link relation, because we want to use a more meaningful relation name when possible. In this case, featuredin, or something similar, is that more specific naming that describes what this relationship actually is.

[andrewserong]

Gotcha, thanks for clarifying. What about attached-to, so https://api.w.org/attached-to? That then gives it a closer connection to how it'll be represented in the UI (i.e. when you click to attach an item in the media library the modal uses the language "Attach to existing content").

I've just updated to rename to https://api.w.org/attached-to to try giving this a clearer, descriptive link relation.

giving this a clearer, descriptive link relation.

Thanks @andrewserong

If it's good with @TimothyBJacobs then it still LGTM

Thanks for re-reviewing! I'll see if there's any feedback overnight and hopefully commit this tomorrow.

[andrewserong]

In 60916:

REST API: Rename post link relation in media endpoint to wp:attached-to

By adding the ​https://api.w.org/ prefix and using a more descriptive name for the link relation, this change creates greater clarity for this part of the API. Note that the renaming of this property is safe, as the API change has not yet made it into a final release.

Follow-up to [60893].

Props andrewserong, mukesh27, ramonopoly, timothyblynjacobs.
Fixes #64034.