Create REST API endpoints to lock, release and takeover post edition

[youknowriad]

Context

In this Gutenberg PR, we're trying to introduce post locking ​https://github.com/WordPress/gutenberg/pull/4217

To do so, we're reusing the existing ajaxActions, and the the non-REST API URLs to take over the posts. Ideally, we'd like to be able to lock, unlock and takeover edition of posts without the need of a page refresh or usage of ajax actions.

Questions

• I wonder if we should return an error in the PUT/DELETE requests on single posts if the post is locked by another user. (Not required for the ticket as a V1 but might be good to think about it).

[aduth]

Post locking is meta of a post. Would it not be enough to at least make assigning / reading this meta from existing post endpoints (if not already possible) to implement post locking, rather than adding new endpoints?

​https://developer.wordpress.org/reference/functions/wp_set_post_lock/

[TimothyBlynJacobs]

More background: ​https://github.com/WP-API/WP-API/issues/2225

[danielbachhuber]

@timothyblynjacobs has volunteered to propose an API design here.

[TimothyBlynJacobs]

I don’t think we should just use an attribute on the post response. The status of a lock isn’t a property of the actual post entity, its a system on top of it. The semantics for post locking aren’t going to map super nicely to REST. And I don’t think we should impose this on the post endpoint.

Necessary Functionality

• Check if the post is locked
• Aquire a lock
• Update a lock
• Take over a post
• Nice to Have: Release a lock. This isn’t currently implemented, the lock will stay there until it expires.

Simple Solution, not really REST semantics. I don’t think that’s necessarily an issue for this kind of endpoint.

• Check Lock
  • GET wp/v2/{base}/{id}/lock
    • User ID
    • Acquired
    • Expires
• Aquire/Takeover a Lock
  • POST wp/v2/{base}/{id}/lock
• Update a lock
  • Heartbeat implementation rejects this if the lock’s user has changed.
  • PUT wp/v2/{base}/{id}/lock
    • WP_Error 409 if user ID of current lock !== current user
• Release a lock
  • DELETE wp/v2/{base}/{id}/lock

An alternate way to distinguish between updating a lock and acquiring a lock besides POST vs PUT would be to use a conditional header like If-None-Match and generate an eTag based off of the user ID acquiring the lock.

So:
GET /lock

ETag: md5( locked_by_id )

POST /lock

POST /lock
If-None-Match: “etag returned by the GET or acquiring a lock”

An issue with it being a separate route is that a client would have to make an additional request to see if the locked state should be shown. This could be solved by adding an embeddable link to the lock endpoint to the post model.

Concerns with this approach.

• Not the most flexible. I could see us wanting multiple locks on a post at the same time for things like that collaborative edit mode that was prototyped.

[mnelson4]

The status of a lock isn’t a property of the actual post entity, its a system on top of it.

I don't follow. Can you explain why you think that? And why that means we shouldn't have it be a property on posts?

It doesn't seem that strange to me to have a "locked" property on posts, which can be updated.

Failing that, I like the simple REST (the first one) you proposed @TimothyBlynJacobs.

[danielbachhuber]

Per conversation in Thursday's #core-restapi chat and @TimothyBlynJacobs's comment above, we're punting this out of 5.0. Because Gutenberg works fine with the existing heartbeat mechanism, it doesn't make sense to rush API design.

[spacedmonkey]

As part of the web stories plugin, I implement my own version of the post locking endpoint ​here.

It is designed to be generic following this pattern.

GET wp/v2/{base}/{id}/lock
POST wp/v2/{base}/{id}/lock
DELETE wp/v2/{base}/{id}/lock

If people are interested, I can work on porting this endpoint to WordPress.

@timothyblynjacobs @youknowriad are either of you interested in this endpoint? If so, should with work be done core or in the gutenberg plugin?

[spacedmonkey]

I have created a POC rest api endpoint ​here. Would love a review for anyone.