[wp-trac] [WordPress Trac] #43316: REST API: Support autosaves

Wed Apr 4 04:08:38 UTC 2018

#43316: REST API: Support autosaves
-------------------------------------------------+-------------------------
 Reporter:  kraftbj                              |       Owner:
     Type:  enhancement                          |      Status:  new
 Priority:  normal                               |   Milestone:  5.0
Component:  REST API                             |     Version:
 Severity:  normal                               |  Resolution:
 Keywords:  has-patch needs-testing needs-unit-  |     Focuses:  rest-api
  tests                                          |
-------------------------------------------------+-------------------------

Comment (by rmccue):

 Replying to [comment:62 azaozz]:
 > Right. The current (non-API) logic is:
 > Save:
 > - User edits the post (a post is always edited as we start with an auto-
 draft).

 It doesn't seem like this is necessarily true; wp_create_post_autosave
 shortcircuits if the post is the exact same, so it seems like an autodraft
 can only be created once there is a change?

 > When saving, the post is always updated and an identical revision is
 always created. Note that revisions (including autosave revisions) also
 provide an "audit trail". That's another reason revisions are not editable
 directly by the users.

 We do already provide the functionality to delete revisions via the REST
 API, so they're not really usable for an audit trail, but rather as a sort
 of long-term undo. Their primary use is to see the evolution of a post
 over time.

 >
 > Auto-save:
 > - User edits the post.
 > - Periodically the client checks for changes. If there are any, the
 client saves the post.
 > - The server has different logic for this save:
 >  - If the post is a draft, it is updated in the db without creating
 another revision.
 >  - If the post is a draft but the post author is different than the
 current user, the post is not updated and a revision is created.
 >  - If the post is published a revision is created without updating the
 post.
 >  - When creating a revision following the above logic, if an autosaved
 revision already exists, it is updated instead of creating another
 autosaved revision. Additionally if the post content is identical to the
 new content that is being auto-saved, the previous autosave revision is
 deleted to prevent having a redundant revision (i.e. if the update of the
 previous autosaved revision will make it identical to the current post,
 there is no need of it).
 >
 > When auto-saving the post may be updated (most common case), or a
 revision may be created, updated or deleted.

 Right now, there's no way to say "update this post, but don't create a
 revision". The basic thing we want for autosaves is the ability to do
 this, but providing this functionality so allows any REST API client to do
 so, which I'm a little uncomfortable about (and which would totally
 destroy any concept of revisions being usable as an audit trail, since now
 changes can be made without being recorded anywhere).

 The proposed autosave process I'm talking about here would allow this, but
 in a very controlled way. Each change would still get a revision, but
 clients would now have the ability to temporarily persist changes while
 the user is still working on them.

 The main thing that seems strange is the special-casing of the post's
 author. If we can remove that special-casing, I think the rest is
 reasonably straightforward to model. Is there a reason for this special-
 casing?

 Changing these I think would make the whole process more predictable for
 clients, and easier to model.

 > This differs a lot from the current workflow. Generally when auto-saving
 in any app (not WP), the actual item is being updated. In WP the logic is
 more complex as we have revisions and states, draft vs. published. If we
 create and update a revision directly instead of updating the current
 item, it will be unexpected.

 I think in order to preserve the concept of revisions as a useful thing,
 we need to do this; the alternative is to allow any client to update a
 post without creating a revision (unless I'm missing something there).

 If clients don't want to use the autosave process, then they can keep
 using the existing process, they'll just potentially end up with lots of
 revisions. I see this autosave concept as similar to database
 transactions: you queue up and persist a bunch of changes, then commit
 them all in one revision at once. This preserves the process of always
 creating revisions, while reducing the amount of noise.

 > This will generally mean that a post will always have an autosaved
 revision. That revision will usually be more recent than the post content,
 and the user will have to manually "restore" that autosave revision before
 continuing to edit. That's not a good UX :) This can happen now too, but
 is relatively rare.

 The client can implement the functionality themselves to automatically
 "restore" the autosave. This is essentially what we're doing already with
 the special-case for the post author, but editors can do it in a more
 consistent way.

 > I don't mind changing how saving and auto-saving works in WP, but we'll
 need to come up with a nice workflow. Unsure if now is the best time as
 this ticket is urgent, but if you think we can manage it in the next 2-3
 days, I'm all for trying :)

 I'm working on the implementation for this at the moment based on the
 latest, so we should have a working example to study.

 > Also, the part: "User hits save: `POST
 /wp/v2/posts/{id}/revisions/{rev_id}`" would be an actual save, i.e. `POST
 /wp/v2/posts/{id}`.

 I was thinking this would be a cleaner way of the client actually
 "committing" the autosaved changes. It avoids the problem where an update
 to a somewhat-unrelated resource (the post) affects a bunch of others (all
 the autosaves). This is the current behaviour though:
 `wp_save_post_revision()` is called by `wp_insert_post()`, and it wipes
 out all the autosaves.

 (Autosaves are conceptually difficult to model as a resource because of
 this.)

 I'll update the proposal to reflect this.

 > This is a "disaster recovery" for a rare edge case that was planned for
 the current (non-API) autosave too. We can remove it if need be.

 If it's a global change, that makes sense; I'd rather track and implement
 it separately I think :)

 (Sorry for the long post again; this is a complex topic.)

--
Ticket URL: <https://core.trac.wordpress.org/ticket/43316#comment:63>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform