What is ETag in REST API: Definition and Usage

An ETag (Entity Tag) is a unique identifier assigned by a server to a specific version of a resource in a REST API. It helps clients and servers efficiently check if the resource has changed, enabling smart caching and reducing unnecessary data transfer.

How It Works

Imagine you have a library book that changes every time a new edition is released. Instead of checking the whole book to see if it’s new, you look at a unique sticker on the cover that changes with each edition. In REST APIs, the ETag acts like that sticker.

When a client requests a resource, the server sends the resource along with an ETag header, which is a unique code representing the current version of that resource. Later, the client can ask the server if the resource has changed by sending the ETag back in a request header called If-None-Match. If the server sees the ETag matches the current version, it replies with a 304 Not Modified status, telling the client to use its cached copy. This saves time and bandwidth.

This mechanism helps avoid sending the full resource again when it hasn’t changed, making web communication faster and more efficient.

Example

This example shows a simple REST API response with an ETag header and how a client uses it to check for updates.

http

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "abc123"

{"name": "Alice", "age": 30}

--- Client Request ---
GET /user/1 HTTP/1.1
If-None-Match: "abc123"

--- Server Response if unchanged ---
HTTP/1.1 304 Not Modified

--- Server Response if changed ---
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "def456"

{"name": "Alice", "age": 31}

Output

200 OK with ETag "abc123" and JSON data
304 Not Modified if resource unchanged
200 OK with new ETag "def456" and updated JSON if changed

When to Use

Use ETag headers in REST APIs when you want to improve performance by reducing unnecessary data transfer. It is especially useful for resources that change infrequently but are requested often, like user profiles, product details, or configuration data.

ETags help clients cache data safely and check if updates are needed without downloading the full resource again. This reduces server load and speeds up client applications.

They are also helpful in distributed systems to avoid conflicts by ensuring clients work with the latest version of a resource.

Key Points

• ETag is a unique identifier for a resource version.
• Clients send If-None-Match with the ETag to check for changes.
• Server replies 304 Not Modified if resource is unchanged.
• Helps reduce bandwidth and improve caching efficiency.
• Useful for resources that change rarely but are requested often.

Key Takeaways

ETag is a unique code representing a resource version in REST APIs.

Clients use ETag with If-None-Match to check if a resource changed.

Servers respond with 304 Not Modified to save bandwidth if unchanged.

ETags improve caching and reduce unnecessary data transfer.

Use ETags for resources that are requested often but change rarely.