Lock a Content Item

A lock is a piece of advice to client applications that some other client is currently modifying all or part of a content item. The correct use of locks ensures that no two clients will simultaneously update the same information. A content item can be locked with two different types of lock:

Resource lock: Locks the entire resource (content item). No other locks can be set on this resource.
Fragment lock: Locks only part of the resource (one field of a content item). Several fragment locks can be set on the same content item as long as they lock different fields. A resource lock, however, cannot be set on a content item locked in this way.

An interactive client such as Content Studio is expected to lock a content item with the appropriate type of lock as soon as a user starts making a modification, and unlock it again when the user either saves the change or explicitly abandons it (for example by clicking on a Cancel button). Similarly, an automated client should lock a content item as soon as it "intends" to carry out an update, both to inform other clients of its intentions and to avoid conflicts when it actually performs the update.

The following terms are used when talking about locks:

Acquire

Locking all or part of a content item is described as acquiring a lock.

Release

Unlocking all or part of a content item is described as releasing a lock. The term forced release is used to describe release of a lock owned by another client.

Lock URI

Locks are exposed by the Content Store's web service as URIs called lock URIs. There are three types of lock URI:

lock collection URI: This URI is returned in a content item resource entry, and is the start point for locking a content item.
Public lock URI: These URIs appear in entries returned from a lock collection URI, and simply indicate that a content item is locked.
Private lock URI: This URI is returned to the client that acquires a lock, and is effectively the key to the lock.

Updating a content item involves the following steps:

GET the resource you want to lock.
Optionally, GET the resource's public locks (if any) from the resource's lock collection URI.
If the resource's existing public locks do not conflict with the lock you require, POST a lock request to the lock collection URI. If successful, the web service returns a private lock URI.
PUT the modified version of the resource. In order for the PUT request to succeed you must include the private lock URI in its HTTP header.
DELETE the private lock URI in order to release your lock.

These steps are described in greater detail in the following sections.