Optimistic Locking and Concurrency

Warning The Apiture Open product line will reach end of life December, 2023. Consumers of the Apiture Open APIs should migrate to the Apiture Digital Banking APIs before that time.


Apiture Digital Banking APIs use optimistic concurrency control or optimistic locking. To help you handle cases when multiple clients make concurrent updates to the same resource, our APIs implement a feature of the HTTP protocol called entity tags.

When you GET a mutable resource, we include an entity tag in the ETag response header. (Other responses also include the ETag: the response of a POST operation that creates a new resource, and PUT or PATCH operations that update the resource.) The value of the entity tag (an opaque string with no meaning) changes each time a resource is updated. If you then update the same resource via PUT, PATCH, or POST, optionally pass the entity tag via the If-Match request header. If the resource has changed since you received the representation, the value of your entity tag does not match the current entity tag on the server. This means another client updated the resource since the entity tag was issued to you. Your operation is rejected (not processed) with a 412 Precondition Failed response.

If you already have a representation of the resource and want to fetch the most recent data, issue a GET request and pass an If-None-Match header with the entity tag (you obtained previously) as its value. If the resource has not been modified (the entity tag values match), the GET request returns 304 Not Modified and no response body. If the resource has changed, the API returns 200 OK and the updated data (or perhaps a 3xx response if the resource has moved).

Note: ETag is preferred over using Last-Modified / If-Unmodified-Since headers, since the Last-Modified header in HTTP does not support sub-second granularity. That is, a resource can change multiple times but its associated Last-Modified date-time stamp might not change, so clients may not know the resource has actually changed.

Operations which return a mutable resource also return an ETag:

  • GET
  • A POST operation that creates a resource
  • PUT
  • PATCH

In addition to concurrency, a secondary reason for using entity tags is to help you handle data caching. If you cache responses from any of the above-mentioned operations that return ETag, also check for Expires and Cache-Control headers. That said, many of our API responses are not cacheable because they contain sensitive data, such as personally identifiable information (PII) or account details.