ETag examples

These examples illustrate the basic use-cases on working with ETags.

A simplified example endpoint returning a list of entities is used so as to focus the description on the important aspects. But these scenarios work the same if filters and sorting are used with an endpoint supporting paging and for endpoints returning a single entity only.

Get list of entities only if it has been changed

For example the first GET will return ETag: "1234" in the response headers and a list of entities:

[
    {
        "id": 1,
        "value": 11
    },
    {
        "id": 2,
        "value": 22
    }
]

Now we add a new header If-None-Match: "1234" and send the request again. There are two possible outcomes depending on whether the data have been modified by someone else or not at all.

1. At least a single entity from the list has been modified by someone else

The API responds with a new value in the ETag header ETag: "5678" and returns all entities (those not modified as well).

[
    {
        "id": 1,
        "value": 33   // <-- the only change happened here
    },
    {
        "id": 2,
        "value": 22
    }
]

2. No entities from the list have been modified by someone else

The API responds with HTTP status code 304 Not modified and returns an empty response.

Update entities only if they were not modified by someone else

First we need to call GET to obtain the latest ETag and a list of entities. For example the API responds with ETag: "1234" in the headers and a list of entities:

[
    {
        "id": 1,
        "value": 11
    },
    {
        "id": 2,
        "value": 22
    }
]

We modify the data and prepare a PUT request. We also add the ETag value into the If-Match: "1234" header. For example we modify a single value:

[
    {
        "id": 1,
        "value": 33   // <-- we changed this
    },
    {
        "id": 2,
        "value": 22
    }
]

Even if you modify just a single entity from a list of entities returned along with the ETag, you must send them all with the same ETag.

When sending a list of entities via the PUT/PATCH method, make sure their IDs and their order are the same as in the GET response which was used to obtain the ETag for this PUT request.

There are two possible outcomes depending on whether the data have been modified by someone else or not at all.

1. At least a single entity from the list has been modified by someone else

The API responds with HTTP status code 412 Precondition Failed and no data will be modified.

2. No entities from the list have been modified by someone else

The API persists the changes into the DB and returns the list of the same entities after all changes (usually the versionDate is not send in the request but it is updated by the API automatically). It also returns an updated value in the ETag header ETag: "5678".

[
    {
        "id": 1,
        "value": 33
    },
    {
        "id": 2,
        "value": 22
    }
]

The PATCH methods work the same as PUT methods accepting a single entity. But PUT methods can be used to create a new entity like when the POST method is used. In such case the value of the If-Match header is ignored.