.. _etag: .. currentmodule:: flask_smorest 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 :meth:`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 :class:`Schema ` that serializes the data. In this case, almost eveything is automatic. Only the call to :meth:`Blueprint.check_etag ` is manual. The :class:`Schema ` must be provided explicitly, even though it is the same as the response schema. .. code-block:: python :emphasize-lines: 2,15,26,34 @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("/") @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 :meth:`Blueprint.set_etag ` manually. The example below illustrates this with no ETag schema, but it is also possible to pass an ETag schema to :meth:`set_etag ` and :meth:`check_etag `. .. code-block:: python :emphasize-lines: 2,8,15,20,25,33,36,43 @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("/") @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 :meth:`Blueprint.check_etag ` in the view function. It can't be automatic. A warning is issued if ETag is enabled and :meth:`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`.