Lock entities

Use optimistic locking to make sure API requests do not interfere with each other and to prevent data loss.

Overview

Optimistic locking is used to prevent data loss when multiple changes are made to the same entity concurrently. We recommend you implement optimistic locking when working with the REST API.

Use the client_lock_stamp field to facilitate optimistic locking using the REST API. This field tracks only changes that require entities to be locked in order to prevent data loss and conflicts. When these changes occur, client_lock_stamp is incremented. client_lock_stamp is not incremented when changes are made that do not require entity locking.

Note: Not all changes require locking, such as internal server-side changes for the entity or changes that are a result of business rule execution on the server-side.

Examples of changes that do not require locking include: Changes to positional attributes (index in the grid), and some relations between entities that are read-only in the entity's Details pane, like hierarchical relations.

The version_stamp field is incremented for all changes on an entity, including changes that do not require incrementing the lock stamp. Having both the version_stamp and client_lock_stamp fields enables updates to be performed without data being locked unnecessarily.

To validate the correctness of the client data and avoid accidental overrides, send the client_lock_stamp field in all update (PUT) requests.

The server then validates the version and returns 500, Internal Server Error, if there is a mismatch.

If you do not send the client_lock_stamp as part of the update request, the server does not validate.

Back to top

Examples

Here are examples of locking the entity while updating it.

In both examples, the client_lock_stamp is sent as part of the request.

The client_lock_stamp does not match the stamp of the entity. Error 500, Internal Server Error, is returned.

*** Request ***
PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects/4444
{
    "description": "This is my updated description",
    "client_lock_stamp": 3  
}	

*** Response ***
{
    "error_code": "platform.version_conflict",
    "correlation_id": "loj0p1ol3q3ksggogmomx2wr7",
    "description": "Other users have updated this entity. Refresh the entity to get these updates and re-apply your changes.",
    "description_translated": "Other users have updated this entity. Refresh the entity to get these updates and re-apply your changes.",
    "properties": {
        "entity_type": "defect",
        "entity_id": "4444"
    },
    "stack_trace": ... ... ... ... 
    "business_error": true
}
*** Request ***
PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects/4444
	{
	   "description": "This is my updated description",
          "client_lock_stamp": 4           
	}	
*** Response ***
{
   "type": "defect",
   "id": "4444"
}

Back to top