REST API Meeting Summary: May 3rd

This post summarizes the REST API component team meeting from May 3rd in #core-restapi (Slack archive).

Decisions around register_meta()

This meeting revolved around finding decisions on remaining questions regarding the approach for adding subtype support to register_meta(). Please read the announcement post for the meeting for background and context.

  • It was decided to go with the fourth approach outlined in the announcement post: Every registration of a meta key is accepted, regardless of whether the same meta key already exists on the same object type in another way. Meta keys registered for an object type and subtype will take precedence over meta keys only registered for an object type (i.e. less specific). This allows us to not having to deal with conflicts. Existing calls without using object types will continue to work – while they are now fallback, chances of a conflict are generally rather low in this way. Nonetheless, a major part of these improvements will involve precise documentation and education (more on that below).
  • Easy-to-understand wrapping functions will be introduced, such as register_post_meta(), unregister_post_meta(), and the same for terms, comments and users. In those functions, we can significantly help DUX: Instead of mentioning the very abstract term “object subtype”, we can here refer to it as the more common terms “post type”, “taxonomy”, etc. respectively.
  • New filters sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype} and auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype} will be introduced for metadata sanitization and metadata capability handling for specific subtypes. If one of these two filters is being used for the given variables, the existing sanitize_{$object_type}_meta_{$meta_key} and auth_{$object_type}_meta_{$meta_key} will not be executed – again, this is because metadata registration for an object type and subtype overrules metadata registration for only an object type.

An updated patch with the above changes is in place to test the current approach, available on the ticket #38323.

Documentation & Recommendations

The existing register_meta() function has not yet seen wide use in REST API-related plugins, so the transition to this new behavior should be smooth. However, should developers continue to omit object subtypes or fail to properly prefix their meta keys, over time the chance of conflicts between or within plugins will increase—therefore precise documentation and education are necessary to make all of this work in the long run.

To aid the transition to the new behavior, it will be recommended to switch existing calls to register_meta() over to include an object subtype. Additionally, we will no longer encourage direct calls to register_meta() when a wrapping function like register_post_meta() is available—this is in line with how it is currently preferable to call get_post_meta() over get_metadata( 'post' ), for example. We will also re-emphasize the importance of prefixing meta keys to ensure uniqueness.

Related Issues

Something that we will want to consider in the future is how to deal with meta keys of the same name that are registered for exactly the same object type and the same subtype. Currently, the second call would simply override the data registered by the first call. Alternatively, we could make the second call fail, keeping the first one the “winner”. However, this is a general problem in many areas in core (think about register_post_type() for example), so this may not be the appropriate point to discuss such a big topic.

May 10th Meeting Agenda

Next week’s meeting on Thursday, May 10th 17:00 UTC will continue to focus on discussing register_meta(), particularly review whether the current patch is a viable solution. We will also try to find an answer to the last, smaller question of the original announcement post, whether comment types should actually be considered subtypes in scope of metadata registration. If there is time left afterwards, we can also discuss the state of the current directly Gutenberg-related work in the REST API – otherwise this will happen the week after.

Please review the register_meta() ticket #38323 and the latest patch there, and chime in with your thoughts on the ticket or by attending the meeting!

#rest-api, #summary