Working With APIs

Optimistic Concurrency

Learn about optimistic concurrency and how it prevents lost data writes.

What is optimistic concurrency?
Permalink Get a link to this section

Optimistic concurrency assumes that multiple transactions can frequently complete without interfering with each other. Connect v2 Catalog and Labor resources support versioning to enable optimistic concurrency.

Applications that integrate with these Connect v2 APIs should assume that when a resource is retrieved, it is the current resource. That resource can be updated and written back. After a resource update request succeeds and the new current version is returned, instances of the resource on other clients are stale. An application should treat the failure to update a stale resource as a concurrency exception.

For example: 2 client endpoints get the same catalog item and then both clients try to update it. Client A modifies the item and sends an update which succeeds and increments the item version number. The item update request from Client B will be rejected because the item that it got is now stale. To correct the problem, Client B re-gets the item, updates it, and sends a new update request.

A typical concurrent write flow
Permalink Get a link to this section

Two clients are trying to update the same catalog item at the same time. The first client updates the item description and writes it back. The second client tries to write back an update on the same item, gets a concurrency error, re-gets the item and writes back an update.

  1. Client A gets catalog item, "Drip coffee".

  2. Client B gets the same "Drip coffee" item.

  3. Client A changes the item description to "Filter coffee" and sends the update, which increments the item version.

  4. Client B tries to update the now stale "Drip coffee" item available_for_pickup field to false.

  5. The Client B update request fails with a VERSION_MISMATCH error.

  6. Client B gets the current version of the "Filter coffee" item and changes the available_for_pickup field to false and completes an update of the item, incrementing the version.

Important

When updating a Connect v2 resource with a version field, updates will fail on PUT if a client endpoint has modified the value of the version field of the resource.