The HTTP protocol states that the client sends a HTTP request to the server where certain business logic is applied and a response is formulated, which is redirected towards the client. In case of synchronous transfer between the two, Python frameworks use WSGI standard, while asynchronous transfer follows ASGI standard. Falcon supports both.

The WSGI/ASGI server provides Request and Response objects in the context data. These objects are used by the responders, hooks, middleware etc. as the parameters. For WSGI apps, the instance of falcon.Request class is processed. In ASGI apps, it represents falcon.asgi.Request class. though different, both the classes are designed to have similar properties and methods so as to minimize the confusion and allow easier portability.

Request

The Request object represents the HTTP request. Since it is provided by the server, this object is not meant to be instantiated directly by the responder methods. This object provides the following properties and methods to be used inside the responder, hooks and middleware methods −

• method − HTTP method requested (e.g., ”GET”, ”POST”, etc.)

• host − Host request header field

• port − Port used for the request. Default one for the given schema is returned (80 for HTTP and 443 for HTTPS)

• uri − The fully-qualified URI for the request.

• path − Path portion of the request URI (not including query string).

• query_string − Query string portion of the request URI, without the
  preceding ”?” character.

• cookies − A dict of name/value cookie pairs.

• content_type − Value of the Content-Type header, or None if the
  header is missing.

• stream − File-like input object for reading the body of the request, if any. This object provides direct access to the server”s data stream
  and is non-seekable.

• bounded_stream − file-like wrapper around stream

• headers − Raw HTTP headers from the request

• params − The mapping of request query parameter names to their values.

• get_cookie_values(name) − Return all values provided in the Cookie header for the named cookie. Alias for the cookies property.

• get_media() − Return a deserialized form of the request stream. Similar to media property.

• get_param(name) − Return the raw value of a query string parameter as a string. If an HTML form with application/x-wwwform-urlencoded media type is POSTed, Falcon can automatically parse the parameters from the request body and merge them into the query string parameters. To enable this functionality, set auto_parse_form_urlencoded to True via App.req_options.

Response

The Response object represents the server”s HTTP response to the client. Like the Request object, the Response object too is not meant to be directly instantiated by the responder.

The responder, hook function or middleware method manipulates this object by accessing following properties and methods −

• status − HTTP status code e.g., ”200 OK”. This may be set to a member of http.HTTPStatus, an HTTP status line string or byte string, or an int. Falcon provides a number of constants for common status codes, starting with the HTTP_ prefix, as in − falcon.HTTP_204.

• media − A serializable object supported by the media handlers configured via falcon.RequestOptions.

• text − A string representing response content.

• body − Deprecated alias for text.

• data − A Byte string representing response content.

• stream − A file-like object representing response content.

• content_length − Set the Content-Length header. It sets the content length manually when either text or data property are not set.

• content_type − Sets the Content-Type header. Falcon”s predefined constants for common media types include falcon.MEDIA_JSON, falcon.MEDIA_MSGPACK, falcon.MEDIA_YAML, falcon.MEDIA_XML, falcon.MEDIA_HTML, falcon.MEDIA_JS, falcon.MEDIA_TEXT, falcon.MEDIA_JPEG, falcon.MEDIA_PNG, and falcon.MEDIA_GIF.

• append_header (name, value) − Set or append a header for this
  response. Used to set cookies.

• delete_header (name) − Delete a header that was previously set
  for this response.

• get_header (name) − Retrieve the raw string value for the given
  header.

• set_cookie (name, value) − Set a response cookie. This method can be called multiple times to add one or more cookies to the response.

• set_header (name, value) − Set a header for this response to a given value.

• set_stream (stream, content_length) − Set both stream and content_length.

• unset_cookie (name, domain=None, path=None) − Unset a cookie in the response. This method clears the contents of the cookie, and instructs the user agent to immediately expire its own copy of the cookie.