Request Handler Guidelines¶
Schemas and Public API Documentation¶
Use the schema.validate
decorator on methods which will automatically
validate the request body and output against the schemas provided. The schemas
must be valid JSON schemas;
readthedocs
for an example.
Additionally, return
the data from the
request handler, rather than writing it back (the decorator will take
care of that).
The docstring of the method, as well as the schemas will be used to generate public API documentation.
class ExampleHandler(APIHandler):
@schema.validate(input_schema=..., output_schema=...)
def post(self):
"""I am the public API documentation of this route"""
...
return data
Assertions¶
Use exceptions.api_assert
to fail when some the client does not meet some
API pre-condition/requirement, e.g., an invalid or incomplete request is
made. When using an assertion is not suitable,
raise APIError( ... )
; don’t use self.fail
directly.
class ExampleHandler(APIHandler):
@schema.validate()
def post(self):
...
api_assert(condition, status_code, log_message=log_message)