Use ETags in ASP.NET Core to Prevent Lost Updates

The following example demonstrates both checks:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;

public sealed record UpdateCustomerRequest(
    string Name,
    string City);

app.MapPut("/api/customers/{id:int}", async (
    int id,
    UpdateCustomerRequest request,
    AppDbContext db,
    HttpContext context) =>
{
    var ifMatch = context.Request.Headers.IfMatch;

    if (ifMatch.Count != 1 || string.IsNullOrWhiteSpace(ifMatch[0]))
    {
        return Results.StatusCode(
            StatusCodes.Status428PreconditionRequired);
    }

    var customer = await db.Customers
        .SingleOrDefaultAsync(customer => customer.Id == id);

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

    var currentETag =
        $"\"customer-{customer.Id}-{Convert.ToBase64String(customer.Version)}\"";

    if (ifMatch[0] != currentETag)
    {
        return Results.StatusCode(
            StatusCodes.Status412PreconditionFailed);
    }

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

    try
    {
        await db.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        return Results.StatusCode(
            StatusCodes.Status412PreconditionFailed);
    }

    var newETag =
        $"\"customer-{customer.Id}-{Convert.ToBase64String(customer.Version)}\"";

    context.Response.Headers.ETag = newETag;

    return Results.NoContent();
});

This endpoint illustrates the main flow, but it is not a complete implementation of the HTTP If-Match grammar. A production API should parse entity-tag lists correctly, support or deliberately reject the wildcard form, and use strong comparison as required by HTTP semantics.

The explicit ETag comparison detects changes that occurred before the record was read. The EF Core concurrency token catches a second update that wins the race after this check but before SaveChangesAsync() completes.

This second check is important. Comparing an ETag in application code without database concurrency protection leaves a window in which another request can modify the record.

The example returns 428 Precondition Required when the client does not provide an ETag. This is an application policy that requires clients to send a precondition. HTTP 428 is defined for requests that must be conditional.

5. Handle a 412 Response on the Client

A client should not automatically retry a failed update using the same ETag. That version is already stale.

Instead, the application should reload the latest resource and let the user decide what to do with the conflicting changes.

A simple JavaScript client can detect the conflict:

async function updateCustomer(id, customer, etag) {
    const response = await fetch(`/api/customers/${id}`, {
        method: "PUT",
        headers: {
            "Content-Type": "application/json",
            "If-Match": etag
        },
        body: JSON.stringify(customer)
    });

    if (response.status === 412) {
        throw new Error(
            "This customer was changed by another user. Reload the record before saving."
        );
    }

    if (!response.ok) {
        throw new Error(`Update failed: ${response.status}`);
    }

    return response.headers.get("ETag");
}

The client must keep the ETag received from the GET response and send it with the update. The API should return the new ETag after a successful update if the client needs to make further conditional changes.

For a cross-origin API, configure CORS to expose the ETag response header and allow the If-Match request header. Otherwise, browser JavaScript may be unable to read the ETag or send the required header.

Common Mistakes to Avoid

Checking the ETag only in application code

A record can change between the comparison and the database update. Use a database concurrency token or an equivalent atomic conditional update.

Generating an ETag that never changes

A static ETag does not detect updates. Derive it from a version token or a reliable representation hash.

Treating a stale update as a server error

A concurrency conflict is normally a precondition failure, not an internal server error. Return a suitable status code and help the client recover.

Automatically retrying with the same ETag

The original ETag is stale. Reload the resource, review the latest values, and submit a new request with the current ETag.

Assuming every database supports rowversion

SQL Server provides a database-generated rowversion mechanism. Other database systems may require different concurrency-token strategies.

Best Practices for Production APIs

1. Generate strong ETags that change when the relevant resource version changes.

2. Require If-Match for updates where lost changes would be harmful.

3. Enforce concurrency at the database level as well as at the HTTP boundary.

4. Return 412 Precondition Failed when the supplied version is stale.

5. Return 428 Precondition Required if the API requires a precondition and the client omits it.

6. Provide a clear conflict-resolution flow in the user interface.

7. Test concurrent updates using separate requests and separate database contexts.

8. Avoid exposing internal database paths or implementation details in error responses.

9. Ensure ETag handling is correct when the API supports multiple representations or content negotiation.

Advantages and Disadvantages

Troubleshooting Common Problems

Every update returns 412

Check whether the client is sending the exact current ETag, including its quotation marks. Confirm that the API generates the same token format when reading and updating the resource.

Concurrent updates still overwrite data

Verify that the database update checks the original concurrency token. An application-level comparison alone is not enough.

The client cannot read the ETag

For cross-origin requests, configure CORS to expose the ETag response header. Also confirm that the API actually returns the header on successful GET responses.

EF Core throws DbUpdateConcurrencyException

Another update may have changed the row after it was loaded. Return a conflict response and let the client reload the current state instead of blindly retrying the same values.

Summary

ETags and the If-Match header provide a standard HTTP approach to preventing lost updates in ASP.NET Core APIs. The client sends the version it originally read, and the server checks that version before accepting a change.

For reliable protection, combine ETag validation with database-level concurrency detection. This closes the race between checking the version and saving the record.

When a conflict occurs, return 412 Precondition Failed and let the client reload or resolve the newer data. This approach protects user changes without requiring the application to lock records throughout an editing session.