Working with resources

This section of documentation covers various topics related with general API design handling specific request workflows like:

  • Dealing with falcon context object.
  • Using hooks and middleware classes.

Dealing with falcon context objects

Falcon’s Request object allows you to store some additional context data under Request.context attribute in the form of Python dictionary. This dictionary is available in basic falcon HTTP method handlers like:

  • on_get(req, resp, **kwargs)
  • on_post(req, resp, **kwargs)
  • on_put(req, resp, **kwargs)
  • on_patch(req, resp, **kwargs)
  • on_options(req, resp, **kwargs)
  • ...

Graceful has slighly different design principles. If you use the generic resource classes (i.e. RetrieveAPI, RetrieveUpdateAPI, ListAPI and so on) or the BaseResource class with graceful.resources.mixins you will usually end up using only the simple resource modification handlers:

  • list(params, meta, **kwargs)
  • retrieve(params, meta, **kwargs)
  • create(params, meta, validated, **kwargs)
  • ...

These handlers do not have the direct access to the request and response objects (the req and resp arguments). In most cases this is not a problem. Access to the request object is required usually in order to retrieve client representation of the resource, GET parameters, and headers. These things should be completely covered with the proper usage of parameter classes and serializer classes. Direct access to the response object is also rarely required. This is because the serializers are able to encode resource representation to the response body with negotiated content-type. If you require additional response access (e.g. to add some custom response headers), the best way to do that is usually through falcon middleware classes or hooks.

Anyway, in many cases you may want to work with some unique per-request context. Typical use cases for that are:

  • Providing authentication/authorization objects using middleware classes.
  • Providing session/client objects that abstract database connection and allow handling transactions with automated commits/rollbacks on finished requests.

Starting from graceful 0.3.0 you can define your resource class as a context-aware using with_context=True keyword argument. This will change the set of arguments provided to resource manipulation handlers in the generic API classes:

from graceful.resources.generic import ListAPI
from graceful.serializers import BaseSerializer

class MyListResource(ListAPI, with_context=True)
    serializer = BaseSerializer()

    def list(self, params, meta, context, **kwargs)
        return {}

And in every non-generic resource class that uses mixins:

from graceful.resources.base import BaseResource
from graceful.resources.mixins import ListMixin

class MyListResource(ListMixin, BaseResource, with_context=True):

    def list(self, params, meta, context, **kwargs):
        pass

The context argument is exactly the same object as Request.context that you have access to in your falcon hooks or middleware classes.

Note

Future and backwards compatibility of context-aware resource classes

Every resource class in graceful 0.x is not context-aware by default. Starting from 0.3.0 the context-awareness of the resource should be explicitly enabled/disabled using the with_context keyword argument in class definition. Not doing so will result in FutureWarning generated on resource class instantiation.

Starting from 1.0.0 all resource classes will be context-aware by default and the with_context keyword argument will become deprecated. The future of non-context-aware resources is still undecided but it is very likely that they will be removed completely in 1.x branch.