Quick Start!

This section of the documentation exists to provide an introduction to the Responder interface, as well as educate the user on basic functionality.

Declare a Web Service

The first thing you need to do is declare a web service:

import responder

api = responder.API()

Hello World!

Then, you can add a view / route to it.

Here, we’ll make the root URL say “hello world!”:

@api.route("/")
def hello_world(req, resp):
    resp.text = "hello, world!"

Run the Server

Next, we can run our web service easily, with api.run():

api.run()

This will spin up a production web server on port 5042, ready for incoming HTTP requests.

Note: you can pass port=5000 if you want to customize the port. The PORT environment variable for established web service providers (e.g. Heroku) will automatically be honored and will set the listening address to 0.0.0.0 automatically (also configurable through the address keyword argument).

Accept Route Arguments

If you want dynamic URLs, you can use Python’s familiar f-string syntax to declare variables in your routes:

@api.route("/hello/{who}")
def hello_to(req, resp, *, who):
    resp.text = f"hello, {who}!"

A GET request to /hello/brettcannon will result in a response of hello, brettcannon!.

Returning JSON / YAML

If you want your API to send back JSON, simply set the resp.media property to a JSON-serializable Python object:

@api.route("/hello/{who}/json")
def hello_to(req, resp, *, who):
    resp.media = {"hello": who}

A GET request to /hello/guido/json will result in a response of {'hello': 'guido'}.

If the client requests YAML instead (with a header of Accept: application/x-yaml), YAML will be sent.

Rendering a Template

If you want to render a template, simply use api.template. No need for additional imports:

@api.route("/hello/{who}/html")
def hello_html(req, resp, *, who):
    resp.html = api.template('hello.html', who=who)

The api instance is available as an object during template rendering.

Setting Response Status Code

If you want to set the response status code, simply set resp.status_code:

@api.route("/416")
def teapot(req, resp):
    resp.status_code = api.status_codes.HTTP_416   # ...or 416

Setting Response Headers

If you want to set a response header, like X-Pizza: 42, simply modify the resp.headers dictionary:

@api.route("/pizza")
def pizza_pizza(req, resp):
    resp.headers['X-Pizza'] = '42'

That’s it!

Receiving Data & Background Tasks

If you’re expecting to read any request data, on the server, you need to declare your view as async and await the content.

Here, we’ll process our data in the background, while responding immediately to the client:

import time

@api.route("/incoming")
async def receive_incoming(req, resp):

    @api.background.task
    def process_data(data):
        """Just sleeps for three seconds, as a demo."""
        time.sleep(3)


    # Parse the incoming data as form-encoded.
    # Note: 'json' and 'yaml' formats are also automatically supported.
    data = await req.media()

    # Process the data (in the background).
    process_data(data)

    # Immediately respond that upload was successful.
    resp.media = {'success': True}

A POST request to /incoming will result in an immediate response of {'success': true}.