Optimistic Locking and Concurrency
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.
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,
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
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,
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),
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).
ETag is preferred over using
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
POSToperation that creates a resource
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
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.