docs/api/media.rst
.. _media:
Falcon allows for easy and customizable internet media type handling. By
default Falcon only enables handlers for JSON and HTML (URL-encoded and
multipart) forms. However, additional handlers can be configured through the
:any:falcon.RequestOptions and :any:falcon.ResponseOptions objects
specified on your :any:falcon.App.
.. note::
WebSocket media is handled differently from regular HTTP requests. For
information regarding WebSocket media handlers, please
see: :ref:`ws_media_handlers` in the WebSocket section.
Zero configuration is needed if you're creating a JSON API. Simply use
:meth:~falcon.Request.get_media() and :attr:~falcon.Response.media (WSGI)
, or :meth:~falcon.asgi.Request.get_media() and
:attr:~falcon.asgi.Response.media (ASGI) to let Falcon
do the heavy lifting for you.
.. tab-set::
.. tab-item:: WSGI
.. code:: python
import falcon
class EchoResource:
def on_post(self, req, resp):
# Deserialize the request body based on the Content-Type
# header in the request, or the default media type
# when the Content-Type header is generic ('*/*') or
# missing.
obj = req.get_media()
message = obj.get('message')
# The framework will look for a media handler that matches
# the response's Content-Type header, or fall back to the
# default media type (typically JSON) when the app does
# not explicitly set the Content-Type header.
resp.media = {'message': message}
resp.status = falcon.HTTP_200
.. tab-item:: ASGI
.. code:: python
import falcon
class EchoResource:
async def on_post(self, req, resp):
# Deserialize the request body. Note that the ASGI version
# of this method must be awaited.
obj = await req.get_media()
message = obj.get('message')
# The framework will look for a media handler that matches
# the response's Content-Type header, or fall back to the
# default media type (typically JSON) when the app does
# not explicitly set the Content-Type header.
resp.media = {'message': message}
resp.status = falcon.HTTP_200
.. warning::
Once :meth:`falcon.Request.get_media()` or
:meth:`falcon.asgi.Request.get_media()` is called on a request, it will
consume the request's body stream. To avoid unnecessary overhead, Falcon
will only process request media the first time it is referenced. Subsequent
interactions will use a cached object.
.. _media_validation:
Falcon currently only provides a JSON Schema media validator; however, JSON Schema is very versatile and can be used to validate any deserialized media type that JSON also supports (i.e. dicts, lists, etc).
.. autofunction:: falcon.media.validators.jsonschema.validate
If JSON Schema does not meet your needs, a custom validator may be implemented in a similar manner to the one above.
.. _content-type-negotiation:
Falcon currently only supports partial negotiation out of the box. By default,
when the get_media() method or the media attribute is used, the
framework attempts to (de)serialize based on the Content-Type header value.
The missing link that Falcon doesn't provide is the connection between the
Accept header provided by a user and the Content-Type header set on the
response.
If you do need full negotiation, it is very easy to bridge the gap using middleware. Here is an example of how this can be done:
.. tab-set::
.. tab-item:: WSGI
.. code:: python
from falcon import Request, Response
class NegotiationMiddleware:
def process_request(self, req: Request, resp: Response) -> None:
resp.content_type = req.accept
.. tab-item:: ASGI
.. code:: python
from falcon.asgi import Request, Response
class NegotiationMiddleware:
async def process_request(self, req: Request, resp: Response) -> None:
resp.content_type = req.accept
Version 3 of Falcon updated how the handling of exceptions raised by handlers behaves:
JSON, an instance of
:class:falcon.MediaNotFoundError should be raised. By default, this error
will be rendered as a 400 Bad Request response to the client.
This exception may be suppressed by passing a value to the default_when_empty
argument when calling :meth:Request.get_media. In this case, this value will
be returned by the call.falcon.MediaMalformedError should be raised. The original exception, if any,
is stored in the __cause__ attribute of the raised instance. By default, this
error will be rendered as a 400 Bad Request response to the client.If any exception was raised by the handler while parsing the body, all subsequent invocations
of :meth:Request.get_media or :attr:Request.media will result in a re-raise of the same
exception, unless the exception was a :class:falcon.MediaNotFoundError and a default value
is passed to the default_when_empty attribute of the current invocation.
External handlers should update their logic to align to the internal Falcon handlers.
.. _custom_media_handlers:
By default, the framework installs :class:falcon.media.JSONHandler,
:class:falcon.media.URLEncodedFormHandler, and
:class:falcon.media.MultipartFormHandler for the application/json,
application/x-www-form-urlencoded, and multipart/form-data media types,
respectively.
When creating your App object you can either add or completely replace all of
the handlers. For example, let's say you want to write an API that sends and
receives MessagePack <https://msgpack.org/>_. We can easily do this by telling
our Falcon API that we want a default media type of application/msgpack, and
then creating a new :class:~falcon.media.Handlers object to map that media
type to an appropriate handler.
The following example demonstrates how to replace the default handlers. Because
Falcon provides a :class:~.falcon.media.MessagePackHandler that is not enabled
by default, we use it in our examples below. However, you can always substitute
a :ref:custom media handler <custom-media-handler-type> as needed.
.. code:: python
import falcon
from falcon import media
handlers = media.Handlers({
falcon.MEDIA_MSGPACK: media.MessagePackHandler(),
})
app = falcon.App(media_type=falcon.MEDIA_MSGPACK)
app.req_options.media_handlers = handlers
app.resp_options.media_handlers = handlers
Alternatively, you can simply update the existing
:class:~falcon.media.Handlers object to retain the default handlers:
.. code-block:: python
import falcon
from falcon import media
extra_handlers = {
falcon.MEDIA_MSGPACK: media.MessagePackHandler(),
}
app = falcon.App()
app.req_options.media_handlers.update(extra_handlers)
app.resp_options.media_handlers.update(extra_handlers)
The falcon module provides a number of constants for common media types.
See also: :ref:media_type_constants.
.. _note_json_handler:
.. note::
The configured :class:`falcon.Response` JSON handler is also used to serialize
:class:`falcon.HTTPError` and the ``json`` attribute of :class:`falcon.asgi.SSEvent`.
The JSON handler configured in :class:`falcon.Request` is used by
:meth:`falcon.Request.get_param_as_json` to deserialize query params.
Therefore, when implementing a custom handler for the JSON media type, it is required
that the sync interface methods, meaning
:meth:`falcon.media.BaseHandler.serialize` and :meth:`falcon.media.BaseHandler.deserialize`,
are implemented even in ``ASGI`` applications. The default JSON handler,
:class:`falcon.media.JSONHandler`, already implements the methods required to
work with both types of applications.
.. autoclass:: falcon.media.JSONHandler :no-members:
.. autoclass:: falcon.media.MessagePackHandler :no-members:
.. autoclass:: falcon.media.MultipartFormHandler :no-members:
.. autoclass:: falcon.media.URLEncodedFormHandler :no-members:
.. _custom-media-handler-type:
If Falcon doesn't have an Internet media type handler that supports your use case, you can easily implement your own using the abstract base class provided by Falcon and documented below.
In general WSGI applications only use the sync methods, while
ASGI applications only use the async one.
The JSON handled is an exception to this, since it's used also by
other parts of the framework, not only in the media handling.
See the :ref:note above<note_json_handler> for more details.
.. autoclass:: falcon.media.BaseHandler :members: :member-order: bysource
.. tip::
In order to use your custom media handler in a :ref:Falcon app <app>,
you'll have to add an instance of your class to the app's media handlers
(specified in :attr:RequestOptions <falcon.RequestOptions.media_handlers>
and :attr:ResponseOptions<falcon.ResponseOptions.media_handlers>,
respectively).
See also: :ref:`custom_media_handlers`.
.. autoclass:: falcon.media.Handlers :members:
.. _media_type_constants:
The falcon module provides a number of constants for
common media type strings, including the following:
.. code:: python
falcon.MEDIA_JSON
falcon.MEDIA_MSGPACK
falcon.MEDIA_MULTIPART
falcon.MEDIA_URLENCODED
falcon.MEDIA_CSV
falcon.MEDIA_PARQUET
falcon.MEDIA_YAML
falcon.MEDIA_XML
falcon.MEDIA_HTML
falcon.MEDIA_JS
falcon.MEDIA_TEXT
falcon.MEDIA_JPEG
falcon.MEDIA_PNG
falcon.MEDIA_GIF