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

[WordPress Trac]

#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 azaozz):

 Replying to [comment:45 danielbachhuber]:
 > From the user's perspective, I see two goals:
 >
 > 1. I should never lose what I'm currently working on (autosaves).
 > 2. I should be able to see, and restore, my history of edits
 (revisions).
 >
 > If we agree these are two ''distinct'' goals, then it would logically
 make sense to have two separate REST API endpoints because there are two
 distinct sets of behaviors:

 Yes, there are two distinct goals and we have two separate REST API
 endpoints for them. Actually we have two separate REST API controllers for
 them: `WP_REST_Autosaves_Controller` and `WP_REST_Revisions_Controller`.

 > 1. The autosaves endpoint is read/write. There is only one 'autosave'
 resource per user. A client can create an autosave for a user, retrieve
 the autosave for the user, and retrieve all autosaves for all users.

 Not quite.

 1. The autosaves endpoint is a duplicate of the `save` endpoint. The only
 reason it exists (in a separate controller) is to pass a flag to the
 server when the client has initiated an automatic save. I'm not sure which
 makes more sense from pure "RESTfull" point of view: having a flag or
 having a separate controller that partially duplicates the
 `WP_REST_Posts_Controller`.
 2. "There is only one 'autosave' resource per user." No. There are no
 separate 'autosave' resources. These are the same 'post' and 'revision'
 resources.
 3. "A client can create an autosave for a user". No. A client cannot
 create an autosave. A client can save the post, and the server decides
 what to do according to its "business logic".
 4. "...retrieve the autosave for the user". Yeah, the client should be
 able to get the latest revision for a post. This has nothing to do with
 who the user is. Autosave revisions can be retrieved through the revisions
 controller. Not really sure we need to duplicate this in the autosave
 controller.
 5. "...and retrieve all autosaves for all users". This can also be done
 through the revisions controller. Not sure we need the duplicate here too.

 > 2. The revisions endpoint is read-only. Revisions are created by server
 when a resource is saved. The client can only retrieve all revisions (I've
 forgotten how we support "restoring" revisions).

 Right. Revisions are typically restored in the client, after the user
 chooses the content. Then the post is saved as usual.

 Revisions can also be deleted by the client which generally shouldn't be
 possible as they are "audit trail". The client is generally "untrusted"
 and shouldn't "mess with" the server logic. Imagine an `author` level user
 managing all revisions of a post they started, including the revisions
 that were made by the editor(s). But this is a different
 discussion/weakness/bug.

 > And then we get in to the programmatic implementation of the
 abstraction:
 >
 > * It seems magical to create a revision based on some algorithm applied
 to the saved data.

 Are you talking about the "disaster recovery when the user was editing for
 6 hours and didn't save even once and at the end there was a (network or
 human) error and they lost all their work" mode? :) There is nothing
 "magical" about it. It's just a rare edge case we decided to cover in the
 server logic. Again, this is the "business logic" when saving a post,
 nothing to do with the client.

 > * Similarly, if revisions are only created when a post is fully saved,
 then I think it makes sense to keep that distinction in the client-side UX
 (i.e. you hit the "Save" button to create a revision).

 Yep, agreed. That is up to the client to decide. This is also the way it
 currently works on the Edit Post screen.

 Also, revisions may be created or deleted at any time depending on the
 server logic. There may be restrictions on how many revisions to keep,
 revisions may be disabled altogether, plugins may decide when and how to
 save a revision or to prevent it from saving. None of this logic belongs
 in the client.

 > * Because autosaves are user-specific, paths and supported operations
 would be:
 >     * `GET /wp/v2/posts/<post-id>/autosaves` - List all autosave
 objects.
 >     * `POST /wp/v2/posts/<post-id>/autosves` - Create a new autosave
 object.
 >     * `GET /wp/v2/posts/<post-id>/autosaves/<user-id>` - Get the
 autosave object for a specific user.

 Autosave revisions are **not** user specific. The user that is also author
 of the post usually doesn't get an autosave revision while editing. When
 saving, the logic for creating autosave revisions looks at who is the post
 author and who is the current user only to prevent content
 loss/overwriting.

 I'm actually thinking we should remove either the "get single autosave" or
 the "get all autosaves" endpoint. Doesn't make sense to have both on top
 of all revisions endpoints (that also retrieve autosaves).

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