.. _media:
Media
=====
.. contents:: :local:
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.
Usage
-----
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.
.. tabs::
.. tab:: 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:: 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.
Validating Media
----------------
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-negotiaton:
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:
.. tabs::
.. tab:: WSGI
.. code:: python
class NegotiationMiddleware:
def process_request(self, req, resp):
resp.content_type = req.accept
.. tab:: ASGI
.. code:: python
class NegotiationMiddleware:
async def process_request(self, req, resp):
resp.content_type = req.accept
Exception Handling
------------------
Version 3 of Falcon updated how the handling of exceptions raised by handlers behaves:
* Falcon lets the media handler try to deserialized an empty body. For the media types
that don't allow empty bodies as a valid value, such as ``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.
* If a handler encounters an error while parsing a non-empty body, an instance of
:class:`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:
Replacing the Default 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 `_. 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 ` 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.
Supported Handler Types
-----------------------
.. 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:
Custom 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` 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 `,
you'll have to add an instance of your class to the app's media handlers
(specified in :attr:`RequestOptions `
and :attr:`ResponseOptions`,
respectively).
See also: :ref:`custom_media_handlers`.
Handlers Mapping
----------------
.. autoclass:: falcon.media.Handlers
:members:
.. _media_type_constants:
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_YAML
falcon.MEDIA_XML
falcon.MEDIA_HTML
falcon.MEDIA_JS
falcon.MEDIA_TEXT
falcon.MEDIA_JPEG
falcon.MEDIA_PNG
falcon.MEDIA_GIF