WordPress.org

Make WordPress Core

Opened 12 months ago

Last modified 5 months ago

#44862 assigned feature request

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

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

Description

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

Change History (14)

#1 @aduth
12 months 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?

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

#3 @SergeyBiryukov
12 months ago

  • Milestone changed from Awaiting Review to 5.0

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


12 months ago

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


11 months ago

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


11 months ago

#7 @danielbachhuber
11 months 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.


11 months ago

#9 @TimothyBlynJacobs
10 months 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.

So:
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 10 months ago by TimothyBlynJacobs (previous) (diff)

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


10 months ago

#11 @mnelson4
10 months 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
10 months 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
10 months ago

  • Milestone 5.0 deleted

#14 @SergeyBiryukov
5 months ago

  • Milestone set to Awaiting Review
Note: See TracTickets for help on using tickets.