The REST API is a hot topic of conversation right now. I spent 3,000 words verbalizing my opinion on it, but there is a lot of good stuff that smart folks have written about the API and its current state. I want to collect some of these and summarize the positions.
As you Post Status readers know, I’ve put an inordinate amount of attention on the REST API, but I do believe that whatever does get included in core (or possible, what doesn’t) will be quite influential on the WordPress project.
Ryan McCue wrote about progressive enhancement with the API. His section on feature detection is important:
We also recognise that the REST API needs the ability to adapt to future versions of WordPress, and we want to avoid as many breaking changes as possible. Building the abilities for feature detection enables forwards-compatibility via progressive enhancement, and gives clients a reliable paradigm to safely check whether a WordPress supports a feature before trying to use it.
The progressive enhancement concept builds heavily on the model already used by browsers for this purpose. If you want to build a site that uses geolocation (e.g.), you can easily detect support for that and build while waiting for browser support, even including polyfills. Feature detection with the REST API can allow the same technique, and allow polyfilling while waiting for the long-tail of sites to update.
Ryan’s post also well describes the difference between “generic” meta support and specific meta support. In that, while all meta is not auto-discovered in the current API, it’s relatively trivial for individual developers to expose specific meta to the API. That should clear up a lot of folks concerns in regard to meta support in the current API.
Adam Silverstein summarized the meeting that started most of the current API debate. In his post, he specifies the challenges ahead, even within the context of the four objects that the REST API lead developers have proposed:
- The main focus has been on the 4 ācoreā objects in WordPress: posts, terms, comments, and users.
- Posts
- Password-protected posts are going to be ignored from the APIĀ until we have a good solution.
- Meta
- Post (and other) meta has beenĀ pushed out into a separate feature plugin led by @jeremyfelt. Discussion is on the github repo.
- The main issue is that thereās no differentiation between meta fields.Ā Meta could be added via the Custom Fields meta box, or by a plugin.
- Enhancing
register_meta()in core would allow opt-in to the meta REST API ā requiring some core work. See the patch on #35658 for details.- There is no current way to explicitly register meta as public.
- We need to support object meta (post, user, comment, term) and object types (custom post types, etc)
- Media
- Mostly complete (itās a custom post type).
- Some special handling around uploading media.
- Autosaves and post previews
- Tricky, but we think we have a solution for that moving forward.
- Working on them in a separate feature plugin instead.
- This will be an enhancement to the API in the future, and doesnāt block compatibility.
- Terms
- Work great.
- Users
- Works great; undergoing final review.
- Comments
- Works; custom comment types are harder until core better supports them.
A number of core developer positions are also stated on that post.
The password protected posts issues is one of the hairier items. Given WordPress’s setup for protecting posts, and especially the cookie authentication, it just doesn’t mesh well with the API. The Github issue goes into more depth on that.
Meta is another challenge. The Meta sub-team at A Day of REST tackled the issue, or at least identifying exactly what the challenge is. In short, you can just put anything in meta, and for the API to know what to expect is near impossible. And the problem is at a lower level than identifying expected field types. For instance, you can put an entire object inside a single value of a serialized string. I mean, that’s just the problem that is unregulated meta fields.
Matt Mullenweg wrote about chicken and eggs. I honestly don’t know how to take anything specific from what he wrote about 90s rap and what makes an album good. But he did make his position more clear in the initial Slack chat and some of the subsequent posts I link above.
He’s also made it quite clear to me that he disagrees with how I am stating his position, and has stated that my positioning of him (and by extension, Automattic under his lead) is sensationalist. While I was more heated in my initial Automattic accusation than I was when I wrote my blog post, he is the CEO of Automattic, and he hasn’t provided a great response to my question about whether the WordPress REST API would be a bigger priority if the .com API didn’t already exist.
He has said multiple times that he’s not against iteration, but would rather see it in the plugin than in core. I think, under that premise, it would never make it to core. It will always be iterating, as you can see from Ryan’s description of progressive enhancement.
Drew Jaynes made a compelling middle ground argument on aĀ WP Tavern article, noting that “shooting for the stars” is natural for Matt inĀ his role as project lead, while others bring it back down to reality. Only time will tell how much Matt will stick to his guns for full admin coverage, but if he blocks the initial API endpoints from going into core, then it’sĀ a bit more of a push than shooting for the stars.
Daniel Bachhuber just wants more concrete feedback from core contributors and lead developers, which is a completely reasonable expectation. Honestly, such definitions of what is expected would have been great a really long time ago.
Amongst all the hubub, beta 12 of the WordPress REST API version 2.0 plugin was released. It’s worth noting, if you’re amazed about the beta-ness going to 12, it’s perpetually in beta until a decision is made about these endpoints going into core. The release post goes into more detail about pulling meta and putting it into its own plugin as well.
Weston Ruter did what I think he called a “thought dump” on the “harmonization possibilities” between menu items and widget areas (a yet-completed REST API endpoint). His thoughts resulted in a Trac proposal for making widget areas a custom post type that would operate similarly to menus, and I think that is an amazing idea.
This Google Spreadsheet is attempting to collect examples of the WordPress REST API (version 2) in production. Add yours!
Consider yourself caught up on the state of the WordPress REST API, for now…
