Item locks [VC 21.3 GEN]

Items can be locked by users to temporarily prevent access from other users. This can be used to prevent users from working with stale and conflicting data. Locks should not be seen as an alternative to access control, as any user that has write access to an item can remove the locks.

If any user attempts to access an item that is locked by another user, HTTP status code 409 Conflict will be returned. For example:

HTTP/1.1 409 Operation would lead to conflict
Context: lock
ID: VX-123
Reason: That entity is locked by another user.
Value: the-name-of-the-other-user

Managing locks

All locks are associated with an expiration date and will be removed after they expire.

Create a lock

POST /item/(item-id)/lock

Creates a new lock for the item with an expiration date. The expiration date is the sum of the timestamp and the duration. If no timestamp and no duration is given, the expiration date will be set to 24 hours forward in time.

Query Parameters:	timestamp (string) – An ISO 8601 timestamp. Defaults to the current time. duration (string) – An ISO 8601 duration. Default is 0.
Status Codes:	200 OK – The lock was created. 409 Conflict – Some other user already holds a lock on that item.
Role:	_lock_write

Example

Create a lock for a specific timestamp:

POST /item/VX-123/lock?timestamp=2010-08-20T15:00:00+02:00

200 OK

Create a lock for 3 hours:

POST /item/VX-123/lock?duration=PT3H

200 OK

Retrieve a lock

GET /item/(item-id)/lock

Retrieves information about the expiration date and which user that holds the lock.

Status Codes:	404 Not Found – Either the item or the lock could not be found.
Produces:	application/xml, application/json – LockDocument
Role:	_lock_read

Example

GET /item/VX-123/lock

<LockDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <id>VX-123</id>
   <user>admin</user>
   <expires>2010-08-20T15:00:00.000+02:00</expires>
</LockDocument>

Delete a lock

DELETE /item/(item-id)/lock

Removes the lock for the item.

Status Codes:	200 OK – The lock was removed.
Role:	_lock_write

Example

DELETE /item/VX-123/lock

200 OK

Extend the expiration date of a lock

PUT /item/(item-id)/lock

Sets a new expiration date for the lock. The expiration date is the sum of the timestamp and the duration. If no timestamp and no duration is given, the expiration date will be set to 24 hours forward in time.

Query Parameters:	timestamp (string) – An ISO 8601 timestamp. Defaults to the current time. duration (string) – An ISO 8601 duration. Default is 0.
Status Codes:	200 OK – The lock was extended.
Role:	_lock_write

Example

POST /item/VX-123/lock?timestamp=2010-08-20T16:00:00+02:00

200 OK