The API Class¶
Falcon’s API class is a WSGI “application” that you can host with any standard-compliant WSGI server.
import falcon
app = falcon.API()
-
class
falcon.
API
(media_type='application/json; charset=UTF-8', request_type=<class 'falcon.request.Request'>, response_type=<class 'falcon.response.Response'>, middleware=None, router=None, independent_middleware=False)[source]¶ This class is the main entry point into a Falcon-based app.
Each API instance provides a callable WSGI interface and a routing engine.
Parameters: - media_type (str, optional) – Default media type to use as the value for the Content-Type header on responses (default ‘application/json’).
- middleware (object or list, optional) –
One or more objects (instantiated classes) that implement the following middleware component interface:
class ExampleComponent(object): def process_request(self, req, resp): """Process the request before routing it. Args: req: Request object that will eventually be routed to an on_* responder method. resp: Response object that will be routed to the on_* responder. """ def process_resource(self, req, resp, resource, params): """Process the request and resource *after* routing. Note: This method is only called when the request matches a route to a resource. Args: req: Request object that will be passed to the routed responder. resp: Response object that will be passed to the responder. resource: Resource object to which the request was routed. May be None if no route was found for the request. params: A dict-like object representing any additional params derived from the route's URI template fields, that will be passed to the resource's responder method as keyword arguments. """ def process_response(self, req, resp, resource, req_succeeded) """Post-processing of the response (after routing). Args: req: Request object. resp: Response object. resource: Resource object to which the request was routed. May be None if no route was found for the request. req_succeeded: True if no exceptions were raised while the framework processed and routed the request; otherwise False. """
See also Middleware.
- request_type (Request, optional) –
Request
-like class to use instead of Falcon’s default class. Among other things, this feature affords inheriting fromfalcon.request.Request
in order to override thecontext_type
class variable. (defaultfalcon.request.Request
) - response_type (Response, optional) –
Response
-like class to use instead of Falcon’s default class. (defaultfalcon.response.Response
) - router (object, optional) – An instance of a custom router to use in lieu of the default engine. See also: Routing.
- independent_middleware (bool) – Set to
True
if response middleware should be executed independently of whether or not request middleware raises an exception.
-
req_options
¶ A set of behavioral options related to incoming requests. See also:
RequestOptions
-
resp_options
¶ A set of behavioral options related to outgoing responses. See also:
ResponseOptions
-
add_error_handler
(exception, handler=None)[source]¶ Registers a handler for a given exception error type.
Error handlers may be registered for any type, including
HTTPError
. This feature provides a central location for logging and otherwise handling exceptions raised by responders, hooks, and middleware components.A handler can raise an instance of
HTTPError
orHTTPStatus
to communicate information about the issue to the client. Alternatively, a handler may modify resp directly.Error handlers are matched in LIFO order. In other words, when searching for an error handler to match a raised exception, and more than one handler matches the exception type, the framework will choose the one that was most recently registered. Therefore, more general error handlers (e.g., for the standard
Exception
type) should be added first, to avoid masking more specific handlers for subclassed types.Parameters: - exception (type) – Whenever an error occurs when handling a request that is an instance of this exception class, the associated handler will be called.
- handler (callable) –
A function or callable object taking the form
func(ex, req, resp, params)
.If not specified explicitly, the handler will default to
exception.handle
, whereexception
is the error type specified above, andhandle
is a static method (i.e., decorated with @staticmethod) that accepts the same params just described. For example:class CustomException(CustomBaseException): @staticmethod def handle(ex, req, resp, params): # TODO: Log the error # Convert to an instance of falcon.HTTPError raise falcon.HTTPError(falcon.HTTP_792)
-
add_route
(uri_template, resource, *args, **kwargs)[source]¶ Associates a templatized URI path with a resource.
Note
The following information describes the behavior of Falcon’s default router.
A resource is an instance of a class that defines various “responder” methods, one for each HTTP method the resource allows. Responder names start with on_ and are named according to which HTTP method they handle, as in on_get, on_post, on_put, etc.
Note
If your resource does not support a particular HTTP method, simply omit the corresponding responder and Falcon will reply with “405 Method not allowed” if that method is ever requested.
Responders must always define at least two arguments to receive
Request
andResponse
objects, respectively. For example:def on_post(self, req, resp): pass
The
Request
object represents the incoming HTTP request. It exposes properties and methods for examining headers, query string parameters, and other metadata associated with the request. A file-like stream is also provided for reading any data that was included in the body of the request.The
Response
object represents the application’s HTTP response to the above request. It provides properties and methods for setting status, header and body data. TheResponse
object also exposes a dict-likecontext
property for passing arbitrary data to hooks and middleware methods. This property could be used, for example, to provide a resource representation to a middleware component that would then serialize the representation according to the client’s preferred media type.Note
Rather than directly manipulate the
Response
object, a responder may raise an instance of eitherHTTPError
orHTTPStatus
.In addition to the standard req and resp parameters, if the route’s template contains field expressions, any responder that desires to receive requests for that route must accept arguments named after the respective field names defined in the template.
A field expression consists of a bracketed field name. For example, given the following template:
/user/{name}
A PUT request to “/user/kgriffs” would be routed to:
def on_put(self, req, resp, name): pass
Individual path segments may contain one or more field expressions, and fields need not span the entire path segment. For example:
/repos/{org}/{repo}/compare/{usr0}:{branch0}...{usr1}:{branch1} /serviceRoot/People('{name}')
Note
Because field names correspond to argument names in responder methods, they must be valid Python identifiers.
Parameters: - uri_template (str) – A templatized URI. Care must be taken to ensure the template does not mask any sink patterns, if any are registered (see also add_sink).
- resource (instance) – Object which represents a REST resource. Falcon will pass “GET” requests to on_get, “PUT” requests to on_put, etc. If any HTTP methods are not supported by your resource, simply don’t define the corresponding request handlers, and Falcon will do the right thing.
Note
Any additional args and kwargs not defined above are passed through to the underlying router’s
add_route()
method. The default router does not expect any additional arguments, but custom routers may take advantage of this feature to receive additional options when setting up routes.
-
add_sink
(sink, prefix='/')[source]¶ Registers a sink method for the API.
If no route matches a request, but the path in the requested URI matches a sink prefix, Falcon will pass control to the associated sink, regardless of the HTTP method requested.
Using sinks, you can drain and dynamically handle a large number of routes, when creating static resources and responders would be impractical. For example, you might use a sink to create a smart proxy that forwards requests to one or more backend services.
Parameters: - sink (callable) – A callable taking the form
func(req, resp)
. - prefix (str) –
A regex string, typically starting with ‘/’, which will trigger the sink if it matches the path portion of the request’s URI. Both strings and precompiled regex objects may be specified. Characters are matched starting at the beginning of the URI path.
Note
Named groups are converted to kwargs and passed to the sink as such.
Warning
If the prefix overlaps a registered route template, the route will take precedence and mask the sink (see also add_route).
- sink (callable) – A callable taking the form
-
set_error_serializer
(serializer)[source]¶ Override the default serializer for instances of
HTTPError
.When a responder raises an instance of
HTTPError
, Falcon converts it to an HTTP response automatically. The default serializer supports JSON and XML, but may be overridden by this method to use a custom serializer in order to support other media types.Note
If a custom media type is used and the type includes a “+json” or “+xml” suffix, the default serializer will convert the error to JSON or XML, respectively.
The
HTTPError
class contains helper methods, such as to_json() and to_dict(), that can be used from within custom serializers. For example:def my_serializer(req, resp, exception): representation = None preferred = req.client_prefers(('application/x-yaml', 'application/json')) if preferred is not None: if preferred == 'application/json': representation = exception.to_json() else: representation = yaml.dump(exception.to_dict(), encoding=None) resp.body = representation resp.content_type = preferred resp.append_header('Vary', 'Accept')
Parameters: serializer (callable) – A function taking the form func(req, resp, exception)
, where req is the request object that was passed to the responder method, resp is the response object, and exception is an instance offalcon.HTTPError
.
-
class
falcon.
RequestOptions
[source]¶ Defines a set of configurable request options.
An instance of this class is exposed via
API.req_options
for configuring certainRequest
behaviors.-
keep_blank_qs_values
¶ bool – Set to
True
to keep query string fields even if they do not have a value (defaultFalse
). For comma-separated values, this option also determines whether or not empty elements in the parsed list are retained.
-
auto_parse_form_urlencoded
¶ Set to
True
in order to automatically consume the request stream and merge the results into the request’s query string params when the request’s content type is application/x-www-form-urlencoded (defaultFalse
).Enabling this option makes the form parameters accessible via
params
,get_param()
, etc.Warning
When this option is enabled, the request’s body stream will be left at EOF. The original data is not retained by the framework.
Note
The character encoding for fields, before percent-encoding non-ASCII bytes, is assumed to be UTF-8. The special _charset_ field is ignored if present.
Falcon expects form-encoded request bodies to be encoded according to the standard W3C algorithm (see also http://goo.gl/6rlcux).
-
auto_parse_qs_csv
¶ Set to
False
to treat commas in a query string value as literal characters, rather than as a comma- separated list (defaultTrue
). When this option is enabled, the value will be split on any non-percent-encoded commas. Disable this option when encoding lists as multiple occurrences of the same parameter, and when values may be encoded in alternative formats in which the comma character is significant.
-
strip_url_path_trailing_slash
¶ Set to
False
in order to retain a trailing slash, if present, at the end of the URL path (defaultTrue
). When this option is enabled, the URL path is normalized by stripping the trailing slash character. This lets the application define a single route to a resource for a path that may or may not end in a forward slash. However, this behavior can be problematic in certain cases, such as when working with authentication schemes that employ URL-based signatures.
-
-
class
falcon.
ResponseOptions
[source]¶ Defines a set of configurable response options.
An instance of this class is exposed via
API.resp_options
for configuring certainResponse
behaviors.bool – Set to
False
in development environments to make the secure attribute for all cookies default toFalse
. This can make testing easier by not requiring HTTPS. Note, however, that this setting can be overridden via set_cookie()‘s secure kwarg.