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 is a technique for managing concurrent access to an entity, and a way to prevent simultaneous updates of resources. When you add an ETag header to a PUT request, multiple changes to the same entity do not overwrite each other.

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.

Procedure

To determine the ETag for the current entity instance, send a GET request with the If-None-Match request header and include the asterisk wildcard character as the header value. For example:
```
GET http://localhost:9080/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/14
Accept application/json ;
Content-Type application/json; charset=UTF-8
If-None-Match="*"
```
where the response format is JSON and the entity ID is 14.
When the entity is retrieved from the server, the ETag information is provided in the response header. For example:
```
200 OK
Content-Type application/json
ETag: "e8f4"
{
  id=14:
  first="John":
  last="Doe":
  email="john_doe@example.com"
}
```
where the ETag is e8f4, the status of the response is 200 (OK), and the entity data includes the entity ID, given name and surname of a customer, and the email address of a customer.
Send a GET, PUT, or DELETE request that includes the If-Match or If-None-Match tags and the ETag value in the request header, as shown in the example.
```
PUT http://localhost:9080/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/14
Accept application/json
Content-Type application/json; charset=UTF-8
If-Match: "e8f4"
{
	id=14:
	email=john_doe@mycompany.org
}
```
where the email of the customer is updated from john_doe@example.com to john_doe@mycompany.org if the ETag specified in the If-Match header in the incoming PUT request matches the ETag in the existing entity instance on the server.