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
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)