Quick Draft: Leverage REST API endpoints

[adamsilverstein]

If the REST API content endpoints were in core, how would we rebuild core features (like Quick Draft) to use it? I am opening this ticket to track work on converting the Quick Draft feature to using the REST API.

The quick draft feature is a meta box on the Dashboard for creating draft posts:

Quick Draft currently uses a simple form to post to post.php and create a the draft. The goal of this ticket would be to switch this action to JavaScript and the REST API. In addition, we would switch the list of recent drafts below the form to load via the API and render dynamically as well as adding a progress indicator and confirmation/error message. Note that the form is already hidden if JavaScript isn't available.

Aaron Rutley has already coded a POC version here: ​https://github.com/AaronRutley/quick-rest-draft

One thing I started noodling on awhile back was Quick Draft to save progress. The use case is similar to the post editor—if you leave your wp-admin open too long, the nonce can expire, and you'll lose your post if attempting to save. I'm not sure if it makes sense to add this as an unrelated enhancement to save to the local browser storage or save a draft to the db.

A Quick update here: I started work on this, still needs some more testing and polishing then I will submit as a patch. In the mean time, here is what I have so far: ​https://github.com/xwp/wordpress-develop/compare/master...adamsilverstein:ticket-38342

If the REST API content endpoints were in core, how would we rebuild core features (like Quick Draft) to use it?

After chatting with @adamsilverstein , my take on this was to do a more thorough overhaul of the existing Quick Drafts, leveraging the ​Backbone.js API client proposed to be merged with the content endpoints. I was interested in seeing what it would look like to have Quick Posts operate exclusively on data from the posts endpoints, bootstrapping data on the initial page load using rest_do_request and maintaining a Backbone collection of drafts in browser state.

WIP: ​https://github.com/aduth/wordpress-develop/compare/master...update/trac-38342-api-quick-draft

Looking good!

Continuing work on this here, i'll give you commit there @aduth so we can collaborate more easily ​https://github.com/adamsilverstein/wordpress-develop/commits/update/trac-38342-api-quick-draft

Contributions & feedback welcome, work in progress.

WIP patch for testing

The above patch is more-or-less functionally complete. The experience should feel much the same as it is currently.

Some thoughts and pain points encountered in the course of implementing this:

• Bootstrapping data helps in displaying recent drafts more quickly, but there's still a delay for as long as it takes for the dashboard script to load. I added some placeholder elements to give the illusion of incoming content and reduce the jarring effect of items suddenly appearing.
• It's still not clear how we'd access certain data from JavaScript. Content such as: formatted dates, links where filters are run server-side (e.g. edit link), truncated content, etc. Script localization, porting functions to JavaScript, and newer browser features like ​Intl.DateTimeFormat (with appropriate fallbacks) can help achieve these. Other content might require filters on the API endpoints return values themselves.
• Quick Draft already requires JavaScript anyways, but it's worth consideration for if and how content should be rendered "isomorphically" (i.e. complete markup sent from the server, but thereafter controlled in the browser). This could help remedy the need for placeholders as the script loads, but the state of tooling is such that the logic would need to be duplicated to implement (rendering in PHP/Backbone, querying from REST API/WP_Query).

Do we need to handle the possibility of the core endpoints being disabled on a site in this change? I guess that question is just a larger general question I had on the topic of swapping out existing use-cases in wp-admin to use the API.

@timmydcrawford : It appears it is possible to filter out the posts endpoint routes:

​https://github.com/WordPress/WordPress/blob/e4a7c0a/wp-includes/rest-api/class-wp-rest-server.php#L701-L711

Unlikely as it might be, would be a good idea to account for this case by checking whether the required endpoints are registered before displaying Quick Drafts.

The consensus on #38339 is that disabling the core endpoints is a bad idea, which makes sense to me.

We'll need to disable/restrict a couple of things in WordPress.com, but IMO it's ok for core to not have to worry about this too much.

Just a quick note on this patch before I forget, the use of 'filter[post_type]' => 'post', is not required here. This is looking cool, though!

A few more questions that came up when working on #38343:

• How do we support filters in existing callbacks (for backwards compatibility) or if we want to add them PHP side for a future feature? Could we start leveraging JavaScript filters?
• What is the best way to add data that is not part of the standard responses?
• How do we handle endpoints/REST API being deactivated for core features?

Milestoning into 4.7 as an enhancement because A) some kind of core usage of REST API endpoints was requested, and B) I would like to see at least the questions/concerns addressed before beta 1, because I think those are important things core needs to answer for if we're shipping these endpoints.

I think this is looking great - on the questions, this is broadly my opinion, however I'll also ask someone else from the REST API team to weigh in.

Bootstrapping data helps in displaying recent drafts more quickly, but there's still a delay for as long as it takes for the dashboard script to load. I added some placeholder elements to give the illusion of incoming content and reduce the jarring effect of items suddenly appearing.

I think the effect is very cool, and I don't really see this as much of a limitation. Right now, it's true that it makes a while to get your admin scripts bootstrapped because the admin loads, well, a lot of stuff, and by doing it this way we are basically accepting it's going to load last, but I think that's ok.

It's still not clear how we'd access certain data from JavaScript. Content such as: formatted dates, links where filters are run server-side (e.g. edit link), truncated content, etc. Script localization, porting functions to JavaScript, and newer browser features like Intl.DateTimeFormat (with appropriate fallbacks) can help achieve these. Other content might require filters on the API endpoints return values themselves.

So, broadly speaking I think we should be looking at shifting a lot of this stuff to the front-end. This like truncated content / excerpts, localized dates etc. In a REST API driven world, content transformation etc is expected to live much more on the client that on the backend. So, yes - I think we should be looking at solving things like date formatting via JavaScript that can then be used in the admin anywhere.

Quick Draft already requires JavaScript anyways, but it's worth consideration for if and how content should be rendered "isomorphically" (i.e. complete markup sent from the server, but thereafter controlled in the browser). This could help remedy the need for placeholders as the script loads, but the state of tooling is such that the logic would need to be duplicated to implement (rendering in PHP/Backbone, querying from REST API/WP_Query).

I'm not sure what the "official" stance on JS compatibility is. Does / should the wp-admin function without JavaScript? I don't think it does very well right now (e.g. how do I insert an image into a post) so I think we may be ok to say that we can require the use of JS for a feature. Given that, and the nature of the WP Admin application, I don't see isomorphic rendering as that important. I was even a little surprised to see this patch does a rest_do_request for the post list, rather than on-load. It makes sense as long as the Quick Draft is always shown, if I hide it in screen options for example, then really we shouldn't be preloading that data (sorry if that case is actually handled), in which case those logic checks, like "is this box actually shown, or is it hidden with css" is much easier to answer from the javascript context, and we can be much smarter about when to load data.

@adamsilverstein:

How do we support filters in existing callbacks (for backwards compatibility) or if we want to add them PHP side for a future feature? Could we start leveraging JavaScript filters?

If this is for backwards compat, I don't see a case for the JS filters - the PHP filters side of things is a little more tricky. For example, as we replace admin-ajax stuff, those used to be filterable in a different way. Given these filters can be quite esoteric I'm not sure that we need to support admin-ajax filters. However, I'm sure there are situations where we _will_ need to support PHP filters, (like prepare_attachment_for_js for example) and in those cases we'll have to do the usual "try and work out the most elegant hack to fire them with the same things as before" type thing that happens whenever we re-build a feature in WordPress. That's not always an easy thing to do, and I don't see a great fix-all solution there, given how different every filter can be.

What is the best way to add data that is not part of the standard responses?

This _can_ be done with adding meta, register_rest_field etc, however I think this should be looked at on a case-by-case basis. If there is data that we are outright missing from the API, let's try to get that into the API. If on the other hand, it's something presentation, that _did_ previously live at the PHP-send-it-over-the-wire-with-the-data level, we should take a fresh look at how to go about achieving the same result from a JavaScript / Front end centric point of view. I appreciate the REST API is a lot more "pure" it it's approach, and that can be frustrating coming from a PHP/WP world where we just put any data we need _anywhere_ to get the job done. I don't want to discard that pragmatism, but I think we should be striving to keep things "RESTful".

Regarding the question, "How do we handle endpoints/REST API being deactivated for core features?", as noted above the consensus on #38339 does seem to be towards preventing de-registering the API endpoints. Since we need to leverage cookie auth for the post editor anyway, and requiring authentication is the most likely way in which the REST API would be locked down, I believe it's safe to put this concern aside. I think Joe touched on the rest.

Personally, I think in the event that the JS attempts to use the REST API and finds it unavailable, it should gracefully accept that situation and display an error to that effect. "Unavailable, something horrible has happened to your WordPress install!" (better worded of course).
I wouldn't worry about a fallback or detecting if it's available before initing the module - just as long as their draft content is still available for them to copy-paste to save via the normal editor.