Locking
Contents
Locking#
Locking is a mechanism to prevent users from accidentally overriding each other's changes.
When a user edits a content object in Plone, the object is locked until the user hits the Save or Cancel button. If a second user tries to edit the object at the same time, she will see a message that this object is locked.
The API consumer can create, read, update, and delete a content-type lock.
Verb |
URL |
Action |
---|---|---|
|
|
Lock an object |
|
|
Get information about the current lock |
|
|
Refresh existing lock |
|
|
Unlock an object |
Locking an object#
To lock an object, send a POST
request to the /@lock
endpoint that is available on any content object in Plone:
POST /plone/front-page/@lock HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i -X POST http://nohost/plone/front-page/@lock -H "Accept: application/json" --user admin:secret
http POST http://nohost/plone/front-page/@lock Accept:application/json -a admin:secret
requests.post('http://nohost/plone/front-page/@lock', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
If the lock operation succeeds, the server will respond with status 200 OK and return various information about the lock, including the lock token. The token is needed in later requests to update the locked object:
HTTP/1.1 200 OK
Content-Type: application/json
{
"created": "1995-07-31T17:30:00+00:00",
"creator": "admin",
"creator_name": "admin",
"creator_url": "http://localhost:55001/plone/author/admin",
"locked": true,
"name": "plone.locking.stealable",
"stealable": true,
"time": 807211800.0,
"timeout": 600,
"token": "0.684672730996-0.25195226375-00105A989226:1477076400.000"
}
By default, locks are stealable.
That means that another user can unlock the object.
If you want to create a non-stealable lock, pass "stealable": false
in the request body.
To create a lock with a non-default timeout, you can pass the timeout value in seconds in the request body.
The following example creates a non-stealable lock with a timeout of one hour:
POST /plone/front-page/@lock HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"stealable": false,
"timeout": 3600
}
curl -i -X POST http://nohost/plone/front-page/@lock -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"stealable": false, "timeout": 3600}' --user admin:secret
echo '{
"stealable": false,
"timeout": 3600
}' | http POST http://nohost/plone/front-page/@lock Accept:application/json Content-Type:application/json -a admin:secret
requests.post('http://nohost/plone/front-page/@lock', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'stealable': False, 'timeout': 3600}, auth=('admin', 'secret'))
The server responds with status 200 OK and returns the lock information:
HTTP/1.1 200 OK
Content-Type: application/json
{
"created": "1995-07-31T17:30:00+00:00",
"creator": "admin",
"creator_name": "admin",
"creator_url": "http://localhost:55001/plone/author/admin",
"locked": true,
"name": "plone.locking.stealable",
"stealable": true,
"time": 807211800.0,
"timeout": 3600,
"token": "0.684672730996-0.25195226375-00105A989226:1477076400.000"
}
Unlocking an object#
To unlock an object, send a DELETE
request to the /@lock
endpoint:
DELETE /plone/front-page/@lock HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i -X DELETE http://nohost/plone/front-page/@lock -H "Accept: application/json" --user admin:secret
http DELETE http://nohost/plone/front-page/@lock Accept:application/json -a admin:secret
requests.delete('http://nohost/plone/front-page/@lock', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
The server responds with status 200 OK and returns the lock information:
HTTP/1.1 200 OK
Content-Type: application/json
{
"locked": false,
"stealable": true
}
To unlock an object locked by another user, send a force DELETE
request to the /@lock
endpoint:
DELETE /plone/front-page/@lock HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"force": true
}
curl -i -X DELETE http://nohost/plone/front-page/@lock -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"force": true}' --user admin:secret
echo '{
"force": true
}' | http DELETE http://nohost/plone/front-page/@lock Accept:application/json Content-Type:application/json -a admin:secret
requests.delete('http://nohost/plone/front-page/@lock', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'force': True}, auth=('admin', 'secret'))
The server responds with status 200 OK and returns the lock information:
HTTP/1.1 200 OK
Content-Type: application/json
{
"locked": false,
"stealable": true
}
Refreshing a lock#
An existing lock can be refreshed by sending a PATCH
request to the @lock
endpoint:
PATCH /plone/front-page/@lock HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i -X PATCH http://nohost/plone/front-page/@lock -H "Accept: application/json" --user admin:secret
http PATCH http://nohost/plone/front-page/@lock Accept:application/json -a admin:secret
requests.patch('http://nohost/plone/front-page/@lock', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
The server responds with status 200 OK and returns the lock information containing the updated creation time:
HTTP/1.1 200 OK
Content-Type: application/json
{
"created": "1995-07-31T17:30:00+00:00",
"creator": "admin",
"creator_name": "admin",
"creator_url": "http://localhost:55001/plone/author/admin",
"locked": true,
"name": "plone.locking.stealable",
"stealable": true,
"time": 807211800.0,
"timeout": 600,
"token": "0.684672730996-0.25195226375-00105A989226:1477076400.000"
}
Getting lock information#
To find out if an object is locked or to get information about the current lock, you can send a GET
request to the @lock
endpoint:
GET /plone/front-page/@lock HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i -X GET http://nohost/plone/front-page/@lock -H "Accept: application/json" --user admin:secret
http http://nohost/plone/front-page/@lock Accept:application/json -a admin:secret
requests.get('http://nohost/plone/front-page/@lock', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
The server responds with status 200 OK and returns the information about the lock:
HTTP/1.1 200 OK
Content-Type: application/json
{
"locked": false,
"stealable": true
}
Updating a locked object#
To update a locked object with a PATCH
request, you have to provide the lock token with the Lock-Token
header:
PATCH /plone/front-page HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Lock-Token: 0.684672730996-0.25195226375-00105A989226:1477076400.000
Content-Type: application/json
{
"title": "New Title"
}
curl -i -X PATCH http://nohost/plone/front-page -H "Accept: application/json" -H "Content-Type: application/json" -H "Lock-Token: 0.684672730996-0.25195226375-00105A989226:1477076400.000" --data-raw '{"title": "New Title"}' --user admin:secret
echo '{
"title": "New Title"
}' | http PATCH http://nohost/plone/front-page Accept:application/json Content-Type:application/json Lock-Token:"0.684672730996-0.25195226375-00105A989226:1477076400.000" -a admin:secret
requests.patch('http://nohost/plone/front-page', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'Lock-Token': '0.684672730996-0.25195226375-00105A989226:1477076400.000'}, json={'title': 'New Title'}, auth=('admin', 'secret'))