Locking

Locking is a mechanism to prevent users from accidentially overriding each others changes.

When a user edits a content object, 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
POST	`/@lock`	Lock an object
GET	`/@lock`	Get information about the current lock
PATCH	`/@lock`	Refresh existing lock
DELETE	`/@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:

POST /news/my-news-item/@lock HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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": "2022-04-08T16:00:00.000Z",
  "creator": "admin",
  "creator_name": "Admin",
  "creator_url": "http://localhost:8000/@users/admin",
  "locked": true,
  "stealable": true,
  "time": "2022-04-08T16:00:00.000Z",
  "timeout": 600,
  "token": "a95388f2-e4b3-4292-98aa-62656cbd5b9c"
}

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 the timeout value in seconds in the request body.

The following example creates a non-stealable lock with a timeout of 1h.

POST /news/my-news-item/@lock HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

{
  "stealable": false,
  "timeout": 3600
}

The server responds with status 200 OK and returns the lock information.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "created": "2022-04-08T16:00:00.000Z",
  "creator": "admin",
  "creator_name": "Admin",
  "creator_url": "http://localhost:8000/@users/admin",
  "locked": true,
  "stealable": false,
  "time": "2022-04-08T16:00:00.000Z",
  "timeout": 3600,
  "token": "a95388f2-e4b3-4292-98aa-62656cbd5b9c"
}

Unlocking an object

To unlock an object send a DELETE request to the /@lock endpoint.

DELETE /news/my-news-item/@lock HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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 /news/my-news-item/@lock HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

{
  "force": true
}

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 /news/my-news-item/@lock HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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": "2022-04-08T16:00:00.000Z",
  "creator": "admin",
  "creator_name": "Admin",
  "creator_url": "http://localhost:8000/@users/admin",
  "locked": true,
  "stealable": true,
  "time": "2022-04-08T16:00:00.000Z",
  "timeout": 600,
  "token": "a95388f2-e4b3-4292-98aa-62656cbd5b9c"
}

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 /news/my-news-item/@lock HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

The server responds with status 200 OK and returns the information about the lock.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "created": "2022-04-08T16:00:00.000Z",
  "creator": "admin",
  "creator_name": "Admin",
  "creator_url": "http://localhost:8000/@users/admin",
  "locked": true,
  "stealable": true,
  "time": "2022-04-08T16:00:00.000Z",
  "timeout": 600,
  "token": "a95388f2-e4b3-4292-98aa-62656cbd5b9c"
}

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 /news/my-news-item HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Lock-Token: a95388f2-e4b3-4292-98aa-62656cbd5b9c
Content-Type: application/json

{
  "title": "My New News Item"
}