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-rest-api 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('/')
class Pet(MethodView):
@blp.etag
@blp.response(PetSchema(many=True))
def get(self):
return Pet.get()
@blp.etag
@blp.arguments(PetSchema)
@blp.response(PetSchema)
def post(self, new_data):
return Pet.create(**new_data)
@blp.route('/<pet_id>')
class PetById(MethodView):
@blp.etag
@blp.response(PetSchema)
def get(self, pet_id):
return Pet.get_by_id(pet_id)
@blp.etag
@blp.arguments(PetSchema)
@blp.response(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.etag
@blp.response(code=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 with API Response Data Using Another Schema¶
Sometimes, it is not possible to use the data returned by the view function as ETag data because it contains extra information that is irrelevant, like HATEOAS information, for instance.
In this case, a specific ETag schema should be provided to
Blueprint.etag
. Then, it does not need to be passed to
check_etag
.
@blp.route('/')
class Pet(MethodView):
@blp.etag(PetEtagSchema(many=True))
@blp.response(PetSchema(many=True))
def get(self):
return Pet.get()
@blp.etag(PetEtagSchema)
@blp.arguments(PetSchema)
@blp.response(PetSchema)
def post(self, new_pet):
return Pet.create(**new_data)
@blp.route('/<int:pet_id>')
class PetById(MethodView):
@blp.etag(PetEtagSchema)
@blp.response(PetSchema)
def get(self, pet_id):
return Pet.get_by_id(pet_id)
@blp.etag(PetEtagSchema)
@blp.arguments(PetSchema)
@blp.response(PetSchema)
def put(self, new_pet, pet_id):
pet = Pet.get_by_id(pet_id)
# Check ETag is a manual action and schema must be provided
blp.check_etag(pet)
pet.update(update_data)
return pet
@blp.etag(PetEtagSchema)
@blp.response(code=204)
def delete(self, pet_id):
pet = self._get_pet(pet_id)
# Check ETag is a manual action, ETag schema is used
blp.check_etag(pet)
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
or equivalently to
Blueprint.etag
.
@blp.route('/')
class Pet(MethodView):
@blp.etag
@blp.response(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.etag
@blp.arguments(PetSchema)
@blp.response(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>')
class PetById(MethodView):
@blp.etag
@blp.response(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.etag
@blp.arguments(PetSchema)
@blp.response(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.etag
@blp.response(code=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.
If ETag is enabled and check_etag
is not called,
a warning is logged at runtime. When in DEBUG or TESTING mode, an exception
is raised.
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.