Make WordPress Core

Opened 6 years ago

Last modified 3 years ago

#44862 assigned feature request

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

Reported by: youknowriad's profile youknowriad Owned by: timothyblynjacobs's profile timothyblynjacobs
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: REST API Keywords:
Focuses: rest-api Cc:



In this Gutenberg PR, we're trying to introduce post locking

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.


  • 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).

Change History (16)

#1 @aduth
6 years ago

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?

#3 @SergeyBiryukov
6 years ago

  • Milestone changed from Awaiting Review to 5.0

This ticket was mentioned in Slack in #core by youknowriad. View the logs.

6 years ago

This ticket was mentioned in Slack in #core by antpb. View the logs.

6 years ago

This ticket was mentioned in Slack in #core by antpb. View the logs.

6 years ago

#7 @danielbachhuber
6 years ago

  • Owner set to timothyblynjacobs

@timothyblynjacobs has volunteered to propose an API design here.

This ticket was mentioned in Slack in #core-restapi by aduth. View the logs.

6 years ago

#9 @TimothyBlynJacobs
6 years ago

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-Match and generate an eTag based off of the user ID acquiring the lock.

GET /lock

ETag: md5( locked_by_id )

POST /lock

POST /lock
If-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.
Last edited 6 years ago by TimothyBlynJacobs (previous) (diff)

This ticket was mentioned in Slack in #core-restapi by timothybjacobs. View the logs.

6 years ago

#11 @mnelson4
6 years ago

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.

#12 @danielbachhuber
6 years ago

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.

#13 @danielbachhuber
6 years ago

  • Milestone 5.0 deleted

#14 @SergeyBiryukov
5 years ago

  • Milestone set to Awaiting Review

#15 @spacedmonkey
3 years ago

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?

#16 @spacedmonkey
3 years ago

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

Note: See TracTickets for help on using tickets.