ETag

ETag is a web cache validation mechanism. It allows an API client to make conditional requests, such as

• GET a resource unless it is the same as the version in cache.

• PUT/PATCH/DELETE a resource unless the version in cache is outdated.

The first case is mostly useful to limit the bandwidth usage, the latter addresses the case where two clients update a resource at the same time (known as the “lost update problem”).

The ETag featured is available through the Blueprint.etag decorator. It can be disabled globally with the ETAG_DISABLED application parameter.

flask-smorest provides helpers to compute ETag, but ultimately, only the developer knows what data is relevant to use as ETag source, so there can be manual work involved.

ETag Computed with API Response Data

The simplest case is when the ETag is computed using returned data, using the Schema that serializes the data.

In this case, almost eveything is automatic. Only the call to Blueprint.check_etag is manual.

The Schema must be provided explicitly, even though it is the same as the response schema.

@blp.route("/")
@blp.etag
class Pet(MethodView):
    @blp.response(200, PetSchema(many=True))
    def get(self):
        return Pet.get()

    @blp.arguments(PetSchema)
    @blp.response(201, PetSchema)
    def post(self, new_data):
        return Pet.create(**new_data)


@blp.route("/<pet_id>")
@blp.etag
class PetById(MethodView):
    @blp.response(200, PetSchema)
    def get(self, pet_id):
        return Pet.get_by_id(pet_id)

    @blp.arguments(PetSchema)
    @blp.response(200, PetSchema)
    def put(self, update_data, pet_id):
        pet = Pet.get_by_id(pet_id)
        # Check ETag is a manual action and schema must be provided
        blp.check_etag(pet, PetSchema)
        pet.update(update_data)
        return pet

    @blp.response(204)
    def delete(self, pet_id):
        pet = Pet.get_by_id(pet_id)
        # Check ETag is a manual action and schema must be provided
        blp.check_etag(pet, PetSchema)
        Pet.delete(pet_id)

ETag Computed on Arbitrary Data

The ETag can also be computed from arbitrary data by calling Blueprint.set_etag manually.

The example below illustrates this with no ETag schema, but it is also possible to pass an ETag schema to set_etag and check_etag.

@blp.route("/")
@blp.etag
class Pet(MethodView):
    @blp.response(200, PetSchema(many=True))
    def get(self):
        pets = Pet.get()
        # Compute ETag using arbitrary data
        blp.set_etag([pet.update_time for pet in pets])
        return pets

    @blp.arguments(PetSchema)
    @blp.response(201, PetSchema)
    def post(self, new_data):
        # Compute ETag using arbitrary data
        blp.set_etag(new_data["update_time"])
        return Pet.create(**new_data)


@blp.route("/<pet_id>")
@blp.etag
class PetById(MethodView):
    @blp.response(200, PetSchema)
    def get(self, pet_id):
        # Compute ETag using arbitrary data
        blp.set_etag(new_data["update_time"])
        return Pet.get_by_id(pet_id)

    @blp.arguments(PetSchema)
    @blp.response(200, PetSchema)
    def put(self, update_data, pet_id):
        pet = Pet.get_by_id(pet_id)
        # Check ETag is a manual action
        blp.check_etag(pet, ["update_time"])
        pet.update(update_data)
        # Compute ETag using arbitrary data
        blp.set_etag(new_data["update_time"])
        return pet

    @blp.response(204)
    def delete(self, pet_id):
        pet = Pet.get_by_id(pet_id)
        # Check ETag is a manual action
        blp.check_etag(pet, ["update_time"])
        Pet.delete(pet_id)

ETag Not Checked Warning

It is up to the developer to call Blueprint.check_etag in the view function. It can’t be automatic.

A warning is issued if ETag is enabled and check_etag is not called.

Include Headers Content in ETag

When ETag is computed with response data, that data may contain headers. It is up to the developer to decide whether this data should be part of the ETag.

By default, only pagination header is included in the ETag computation. This can be changed by customizing Blueprint.ETAG_INCLUDE_HEADERS.