OCAPI Resource States

A resource state represents the server-side state of a specific resource, for example, a basket or a customer. It’s a string token, baked on all the resource property information.

OCAPI exposes resource state information via the _resource_state property in the response payload (body). The response contains either a single resource state or multiple resource states in case calling collection or search resources. In case of body-less responses (for example, HEAD) the resource state is exposed via x-dw-resource-state response header.

Resource states provide an OPTIONAL mechanism to implement Optimistic Locking in your client. They can be used to prevent collisions between concurrent requests, for example, to overcome the "lost update" problem.

A strong Etag covers not only the server-side resource state itself, but also the whole HTTP response on bit level. Means, it covers also the fact that compression (for example, gzip) is used or not. In scenarios where proxies are in between this might lead to unforeseen behaviours. E.g in case the client doesn't request compression, but there’s compression between the proxy and the server: Some proxies append "-gzip" to the Etag value, others absorb the Etag completely.

OCAPI uses the term "resource_state" to clearly differentiate the concept from Etags. OCAPI isn’t supporting Etags anymore.

To use the resource state for optimistic locking you have to include the resource state from the last server response in your next state changing (DELETE, PATCH, POST, PUT) request. You should always prefer to use the _resource_state property in the body. In case the requested API doesn't have a body use the x-dw-resource-state header. Whenever a resource state is part of a client's request, OCAPI verifies it by comparing the given value with the server resource state. If both resource states are equal the operation is executed, otherwise an HTTP 409 ResourceStateConflictException fault is returned. In case of a create request (for example, with PUT) where the resource isn’t expected to be existing (with not_exists state), the returned fault is an HTTP 409 ResourceAlreadyExistsException instead.

Whenever your application performs state changing (DELETE, PATCH, POST, PUT) operations and there’s a likelihood of concurrent requests, we recommend leveraging optimistic locking on base of resource states.

OCAPI exposes the resource state as _resource_state property in response body and as x-dw-resource-state header.

A resource state can be passed to any state changing method (DELETE, PATCH, POST, PUT). If no resource state is passed, the resource is overwritten, updated, or deleted without any further notice on base of the default HTTP method behavior. If a resource state is passed, it’s verified against the server resource state. If both states don’t match, a ResourceStateConflictException or ResourceAlreadyExistsException fault is responded. When the API user expects a resource not to exist (for example, during resource creation), the resource state not_exists can be passed. This prevents existing resources from being accidentally overwritten.

For every writing operation on a resource, a resource state token can be passed, but doesn’t have to. If no token is passed, the resource is overwritten, updated, or deleted without any further notice. If a resource state is passed, it’s checked against the server state of the resource. If both states don’t match, a 409 status code is retrieved. When the API user expects a resource not to exist, a resource state not_exists must be passed (for a create request).