Request Service Options - eTags

What is eTag?

An eTag also called an entity tag is an HTTP response header field that includes an identifier for the specific version or the state of the resource at the time the request was sent. This identifier helps to differentiate between the different versions of the resource and to check if the caches at the client side hold the updated representation of the state of the resource.

How do they work?

Let’s try to understand what is meant by eTags and how these options work.

If the client wants to check if the caches of a resource are usable or fresh, it can send the eTag in the If-None-Match header field in the request to the server. The server will match the client’s eTag with the one that it has for the current version of the resource. If the ETags match, the server will not send any representation of the state of the resource in the response implying that the client’s caches are fresh and usable.

Two eTag Use-Cases

There are two major uses of eTags in API requests:

• Data Caching

• Concurrency Control.

Let’s investigate these uses one by one. For now, let’s see how this Data Caching works with a use case.

If None Match eTag

So, we will make an API call to one of the endpoint operations of Box APIs. Here, we have a dataflow in which we are making an API call to fetch file details from one of the files on our Box account.

We will send a GET request to the /file/{fileid} resource with the help of the API client and API connection object. We have configured the API connection object in a shared action file. From the API documentation site, we can see that Box supports OAuth 2 authentication and the grant type of authorization code. Hence, we have already generated our access code after providing the client credentials from our Box app.

Coming back to our flow, let’s open the properties of the API Client object. Here, we are using the shared action API connection object that is providing the base URL. We have specified the HTTP method of GET and provided the name of the resource. Here, the curly brackets specify that the path parameter of file id will be passed along the request to fetch the information on the file related to that file id. In our flow, we are providing the file id through the constant object.

From the API documentation of Box APIs, we can see that the if none match header is supported for the endpoint at which we are making a call in our dataflow.

Now, if we go to the Service options screen of the API Client object, we can see that we have a checkbox to enable eTags which further gives us two checkboxes of,

• Retrieve if None Match Header

• Update Using If-Match Header.

We need to enable the eTag and the If-None-Match header checkbox.

When the request is sent to the server to fetch the file information for the first time via the GET API request, the response will be returned with an eTag value. This eTag value along with the response will be stored in the response caches at the client side.

• The field of “Is cached response” in the response info node will be returned True because we are making the call for the first time and receiving the response from the server that will be cached.

• In the future, if the client makes an API call again to fetch the file information, the eTag in response caches will be first compared with the latest eTag from the Server. So, for the consecutive API calls having the same cached eTag, we will see the “Is Cached Response” field as true.

• In case, the file has not changed or updated, and the caches are reusable. The server will send a No modification response as we can see in our job trace. This means that the server does not have to send the requested information again in the response instead the client can use its response caches.

So, this is how eTags help to prevent unnecessary download and retrievable of information in turn saving the server’s bandwidth and request processing time.

If-Match eTag

Let’s look at another use case of eTag related to concurrency control.

It is possible that more than one client is sending requests to update the resources of the server. Then, to prevent loss of changes and to detect simultaneous updates, the client can send an eTag in the If-Match header field in the request to the server, if another client updates the resource in between or the file is modified, the server can compare the client’s eTag with its own current one and if they don’t match, the server can prevent clients from overwriting the changes or it will ensure that the latest version of the resource gets updated.

Let’s try to understand it with the help of a use case.

• We will make two update API calls to change the name of a file uploaded at our Box account. But, in between the two calls we will make some changes to the file at the server side and see how the eTags play their part in ensuring consistency.

• Here, we have a dataflow in which we are making a PUT request to update the name of the file associated with the file ID of “983656708053” on our Box account. From the API documentation, we can see that the if-match header field is supported in the PUT /file/{fileid} endpoint of Box APIs so in the API client service options, we will enable the If-Match Header checkbox.

• The API client first checks if an eTag and response corresponding to this endpoint URL already exists in the cache. In the job trace, we can see that there is no eTag in the response caches because we are making the update request for this file for the first time.

• Behind the scenes, the client first makes a Get call to the same endpoint URL and stores the eTag and response in its cache. Next, a PUT request is sent to the same endpoint URL including the eTag received earlier as the value of the If-Match header.

• The server processes the update request and the eTag and the response returned is cached as the eTag received matches to the most recent version of the resource at the server.

This concludes our discussion on the eTag request service options and how they help with response caching and maintaining concurrency control in Astera API Management.