Updating and retrieving entities by using ETag
An entity tag, or ETag, is a mechanism that is provided by the HTTP protocol so that a browser client or a script can make conditional REST requests for optimistic updating or optimized retrieval of entities.
About this task
- Optimistic updating
- When an entity is created or updated by event processing, or by
a REST request or other system activity, the entity instance is flagged
with a unique ETag. By comparing the ETag information in an existing
entity with the incoming ETag in a PUT request, the REST API determines
when a requested update overwrites the current entity instance. You
can add the If-Match request header and ETag information to your PUT
request to control updates to entities, therefore ensuring that no
information is lost during the update. First, you retrieve the current
entity data by using a GET request that includes the If-Match request
header. The ETag information is returned along with the entity content.
Then, you send a PUT update request that includes the If-Match request
header with the ETag information from the previous GET request. A
comparison of the ETags determines whether the entity was modified
since the previous request. If the ETags match, then the entity was
not modified and the update is processed. If the ETags do not match,
then the entity was recently updated by another request or process.
In this case, the entity update is not updated. The response to your
PUT request displays the 412 Precondition Failed status
code.
You can add ETag to a GET request for optimized entity retrieval, which returns entities that changed since the previous request, but not entities that are unchanged.
- Optimized retrieval
- Add a conditional request header and the ETag information to GET requests to retrieve only the entity, or group of entities, that changed since the previous request or update. This method conserves system resources because it returns recently updated entities instead of returning all entities. First, you retrieve the ETag information from the entity or entities by sending a GET request with a wildcard character as the ETag value, for example: If-None-Match: "*". Because this wildcard does not match the ETag in the current instance of the entity, the ETag information is returned in the header of the response. Then, send a second GET request that includes the If-None-Match header and the ETag. The entity retrieval is successful if the ETag does not match and the response includes changed entities. The retrieval fails if there are no changed entities, and in this case, the response includes the 304 Not Modified status code, but no entity content is returned.