How to Use ETags in ASP.NET Core to Prevent Users from Overwriting Each Other’s Changes

public record UpdateCustomerRequest(
    string Name,
    string City);

[HttpPut("{id:int}")]
public async Task<IActionResult> UpdateCustomer(
    int id,
    UpdateCustomerRequest request,
    CancellationToken cancellationToken)
{
    if (!Request.Headers.TryGetValue(
        "If-Match", out var ifMatchValues))
    {
        return StatusCode(
            StatusCodes.Status428PreconditionRequired,
            "The If-Match header is required.");
    }

    if (ifMatchValues.Count != 1 ||
        string.IsNullOrWhiteSpace(ifMatchValues[0]))
    {
        return BadRequest("Provide one valid If-Match value.");
    }

    var customer = await _dbContext.Customers
        .SingleOrDefaultAsync(
            customer => customer.Id == id,
            cancellationToken);

    if (customer is null)
    {
        return NotFound();
    }

    string currentETag = CreateETag(customer.RowVersion);

    if (!string.Equals(
        ifMatchValues[0],
        currentETag,
        StringComparison.Ordinal))
    {
        return StatusCode(
            StatusCodes.Status412PreconditionFailed,
            "The customer has changed. Reload the latest version.");
    }

    customer.Name = request.Name;
    customer.City = request.City;

    try
    {
        await _dbContext.SaveChangesAsync(cancellationToken);
    }
    catch (DbUpdateConcurrencyException)
    {
        return StatusCode(
            StatusCodes.Status412PreconditionFailed,
            "The customer changed during the update. Reload and try again.");
    }

    Response.Headers.ETag = CreateETag(customer.RowVersion);

    return Ok(new
    {
        customer.Id,
        customer.Name,
        customer.City
    });
}

Why both ETag checks are necessary

The first check compares the client's ETag with the version currently loaded from the database. If the client is already working with an outdated version, the API rejects the request before changing the entity.

However, another request could update the database after this comparison but before SaveChangesAsync() completes.

The database concurrency token handles this second case. EF Core checks the original row version when issuing the update. If the row has changed, it throws DbUpdateConcurrencyException.

The API converts that exception into HTTP 412 Precondition Failed, telling the client that its condition is no longer valid.

This second check closes an important race condition that a simple ETag comparison in application code cannot prevent.

The example uses a simplified If-Match implementation that accepts one exact ETag. HTTP also supports wildcard and multiple-tag forms of If-Match; an API that needs full HTTP conditional-request support should parse and handle those forms according to the protocol.

Step 4: Handle the Response in the Client

The client must save the ETag received from the GET request and include it in the update request.

For example, a JavaScript client can do the following:

const response = await fetch("/api/customers/42");

if (!response.ok) {
    throw new Error("Unable to load customer.");
}

const customer = await response.json();
const etag = response.headers.get("ETag");

const updateResponse = await fetch("/api/customers/42", {
    method: "PUT",
    headers: {
        "Content-Type": "application/json",
        "If-Match": etag
    },
    body: JSON.stringify({
        name: customer.name,
        city: "Delhi"
    })
});

if (updateResponse.status === 412) {
    console.log("The customer changed. Reload before saving.");
} else if (!updateResponse.ok) {
    throw new Error("Unable to update customer.");
}

In a real application, the user interface should handle a conflict more carefully than simply logging a message. It can show the latest server data, preserve the user's unsaved changes, and let the user decide how to combine the two versions.

The client should also check that the ETag exists before sending the update.

Understanding the HTTP Status Codes

Choosing the correct status code helps clients understand why an update failed.

A consistent status-code strategy makes it easier for frontend applications and other API clients to handle conflicts correctly.

Common Mistakes to Avoid

Generating an ETag that never changes

If the server always returns the same ETag, the client cannot detect newer versions. Generate the ETag from a reliable version token and ensure that every relevant update changes that token.

Checking the ETag without database concurrency control

A comparison performed before saving does not protect against changes that happen immediately afterward. Use a database concurrency token or an equivalent atomic conditional update.

Returning a new ETag before the database update succeeds

The ETag must represent the saved version, not an expected version. Return it only after the update succeeds.

Overwriting the ETag in the client

If the client replaces its stored ETag with an outdated value or ignores the header, concurrency protection may fail. Keep the version associated with the data the user is editing.

Treating a conflict as an ordinary failure

A concurrency conflict does not necessarily mean the user made a mistake. The client should help the user reload, compare, or merge changes instead of silently retrying the same outdated request.

Best Practices for Using ETags in ASP.NET Core

1. Use database concurrency tokens when multiple requests can update the same record.

2. Require If-Match for update operations where overwriting another user's changes is unacceptable.

3. Return the updated ETag after a successful write so the client can use it for the next operation.

4. Keep API response versions consistent with the representation being protected.

5. Return 412 Precondition Failed when an existing ETag no longer matches.

6. Return 428 Precondition Required when your API requires a conditional update but the client omits the precondition.

7. Preserve unsaved user changes when handling conflicts in the user interface.

8. Test concurrent updates using two requests that start with the same ETag.

9. Remember that ETags are not authorization tokens. Continue to enforce authentication and resource-level authorization.

10. If using an ETag based on a representation's content, ensure that changes to the relevant representation produce a different validator. For database-backed updates, a concurrency token is often easier to use consistently.

Advantages and Disadvantages of ETags

Advantages

• Prevents silent overwriting of newer changes when the server enforces conditional updates correctly.

• Does not require locking a record while a user edits it.

• Works through standard HTTP headers.

• Helps REST APIs communicate resource-version conflicts clearly.

• Can be combined with database concurrency tokens for stronger protection.

Disadvantages

• Requires the server and client to manage ETags correctly.

• Adds concurrency-handling logic to update endpoints.

• Requires a conflict-resolution strategy in the user interface.

• Needs careful implementation when resources include related data or multiple database records.

• Does not automatically merge conflicting changes.

Summary

ETags provide a practical way to prevent users from overwriting each other's changes in ASP.NET Core applications. The server returns an ETag with the resource, and the client sends that value through the If-Match header when updating it.

The server checks whether the version still matches and rejects outdated requests with 412 Precondition Failed. For database-backed applications, combining ETags with EF Core concurrency tokens protects against conflicts that occur between the initial check and the database update.

The key is to treat concurrency as part of the API design. Validate the client's version, let the database detect simultaneous updates, and give users a clear way to resolve conflicts without losing their work.