ETags

ETags ensure atomicity of changes, bring control over possible problems, and they transfer the responsibility for the solutions to the integrators.

What is an ETag

The ETag response-header field is an identifier of the current version of the entity or entities.

The If-None-Match request-header field helps save bandwidth, as the API does not need to resend a full response if the content has not changed.

The If-Match request-header field helps prevent simultaneous updates of a resource from overwriting by a third party.

HTTP Response

The API returns the "ETag" header in the response of all entity-based endpoints for all HTTP methods.

ETag: "5C6FEF0BAD91914172B353E157219626"
Access-Control-Expose-Headers: ETag
...

HTTP Request

Some endpoints require "If-Match" or support "If-None-Match" headers in the request. Use the GET method to obtain the current ETag value.

• GET - support "If-None-Match" header and return empty response if entities have not been changed.

• POST - no ETag value is required or supported in the request headers.

• PUT, PATCH - require the ETag value in the "If-Match" header and fail if entities were changed.

• DELETE - no ETag value is now required in the "If-Match" header (temporal only - will be required).

Please see the examples on a dedicated page.

The endpoints returning a list of entities calculate a single ETag value from all the entities in the returned list. So if any entity in the response is changed, the returned ETag value will be different.

When sending a list of entities via the PUT/PATCH method, make sure their IDs and their order are the same as in the GET response which was used to obtain the ETag for this PUT request.

For GET endpoints supporting paging, the ETag is calculated from entities of the current page.

For GET endpoints supporting fused entities, the ETag is calculated from the main entities only (sub-entities are not taken into account and must be updated via their own endpoint if needed).

HTTP Status Codes (ETag-related)

• 200 OK (Any method when finished successfully)

• 304 Not Modified (GET method with "If-None-Match" header if the entity has not been changed)

• 404 Not Found (GET method did not find any matching entity)

• 409 Conflict (PUT/PATCH method on entity failed "versionDate" verification)

• 412 Precondition Failed (PUT/PATCH method with "If-Match" header when entity has been changed)

• 428 Precondition Required (PUT/PATCH method was not called with ETag in the "If-Match" header)

• 500 Internal Server Error (Any method unexpectedly failed)

All status codes can be found here.