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 | 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 (16)
#2
@
6 years ago
More background: https://github.com/WP-API/WP-API/issues/2225
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
@
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
@
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
- GET wp/v2/{base}/{id}/lock
- 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.
This ticket was mentioned in Slack in #core-restapi by timothybjacobs. View the logs.
6 years ago
#11
@
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
@
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.
#15
@
4 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?
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/