kennethreitz/responder

Responder

Web services for humans.
A familiar HTTP Service Framework for Python, powered by Starlette.

Documentation · Quickstart · Tour · Examples · Changelog

import responder

api = responder.API()


@api.get("/hello/{name}")
def hello(req, resp, *, name):
    resp.media = {"hello": name}


if __name__ == "__main__":
    api.run()

$ pip install "responder[orjson]"
$ python app.py

Open http://127.0.0.1:5042/hello/world. That's it.

Responder is the friendly request/response shape of Flask and Falcon, brought to ASGI with Starlette underneath. Every view receives a req and a resp. Read from one, write to the other. Sync and async views both work.

Why Responder?

Responder is for people who like small, expressive web frameworks with real batteries included.

The Shape

Routes look like Python strings, because they are meant to be read.

@api.get("/users/{user_id:int}")
def get_user(req, resp, *, user_id):
    resp.media = {"id": user_id, "name": "Ada"}

Write the response you mean:

resp.text = "hello"
resp.html = "<h1>Hello</h1>"
resp.media = {"ok": True}       # JSON by default, YAML/msgpack by negotiation
resp.file("report.pdf")         # content type detected for you
resp.status_code = 201
resp.headers["Location"] = "/items/1"

Read requests without ceremony:

@api.post("/echo")
async def echo(req, resp):
    payload = await req.media()
    resp.media = {"you_sent": payload}

Return values work too, when that style feels right:

@api.get("/ping")
def ping(req, resp):
    return {"pong": True}

A Real Endpoint

Responder can stay tiny, but it does not stop at toy apps.

from pydantic import BaseModel, Field

import responder
from responder.ext.auth import BearerAuth


class ItemIn(BaseModel):
    name: str = Field(min_length=1)
    price: float = Field(gt=0)


class ItemOut(ItemIn):
    id: int


class User(BaseModel):
    name: str
    scopes: list[str]


api = responder.API(
    title="Store API",
    version="1.0",
    openapi="3.1.0",
    docs_route="/docs",
    request_id=True,
)

users = {"secret-token": User(name="Ada", scopes=["items:write"])}
auth = BearerAuth(verify=lambda token: users.get(token), bearer_format="opaque")
writer = api.policy("writer", auth.requires("items:write"))


@api.post(
    "/items",
    auth=writer,
    status_code=201,
    summary="Create an item",
)
def create_item(req, resp, *, item: ItemIn, user) -> ItemOut:
    return ItemOut(id=1, **item.model_dump())

You get validation, auth enforcement, a documented request body, a documented response body, 401/403/422 Problem Details responses, request IDs, and Swagger UI at /docs. The same inference works for collections:

@api.get("/items")
def list_items(req, resp) -> list[ItemOut]:
    return items

Contracts can stream too. Each event is validated and serialized as it is yielded, OpenAPI carries the item schema, and generated clients expose a lazy iterator instead of buffering the response:

from collections.abc import AsyncIterator


@api.sse("/inventory/events", heartbeat=15)
async def inventory_events(
    req, resp
) -> AsyncIterator[responder.SSE[ItemOut]]:
    async for item in inventory.watch():
        yield responder.SSE(item, event="item", id=item.id)


@api.ndjson("/inventory/export")
async def inventory_export(req, resp) -> AsyncIterator[ItemOut]:
    async for item in inventory.all():
        yield item

What's Included

v9 Highlights

Responder 9 tightened the production story while keeping the familiar API:

• Multipart uploads stream from the wire and spool to disk instead of buffering entire files in memory.
• Request bodies are capped at 100 MiB by default; pass API(max_request_size=None) for the legacy unlimited behavior.
• API(csrf=True) adds session-bound CSRF protection for unsafe requests, with per-route opt-outs for webhooks.
• API(trust_proxy_headers=True) rewrites scheme, host, and client IP from trusted reverse-proxy headers.
• Framework-generated errors use RFC 9457-style application/problem+json responses by default.
• OpenAPI documents operational responses such as CSRF 403, body-cap 413, rate-limit 429, fail-closed limiter 503, validation 422, and timeout 504 where they can actually happen.

Upgrading from an earlier major version? Start with the v9 migration guide.

Installation

$ pip install "responder[orjson]"

This is the recommended installation on standard GIL-enabled CPython: Responder detects orjson automatically and uses it for faster JSON response encoding. Python 3.11 and newer are supported.

Feature combinations:

$ pip install "responder[orjson,server]"   # Granian production server
$ pip install "responder[graphql,orjson]"  # GraphQL with Graphene
$ pip install "responder[jwt,orjson]"      # JWT auth helpers

With uv:

$ uv add "responder[orjson]"

Free-threaded CPython builds (3.14t and 3.15t) should install the base package with pip install responder. Responder gracefully falls back to the standard-library JSON encoder when orjson is unavailable; no application code changes are required.

Run It

# app.py
import responder

api = responder.API()


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


if __name__ == "__main__":
    api.run(port=8000)

$ python app.py

Or through the CLI:

$ responder run app.py

OpenAPI and Clients

Turn on OpenAPI with two arguments:

api = responder.API(
    title="Acme API",
    version="1.0",
    openapi="3.1.0",
    docs_route="/docs",
)

Responder builds the schema from routes, type hints, Pydantic models, auth helpers, and framework behavior. The docs UI appears at /docs, the schema at /schema.yml, and client code can be generated for Python, JavaScript, TypeScript, Ruby, and PHP.

$ responder client --class-name StoreClient --output store_client.py app:api

Examples Worth Reading

Run most examples with:

$ responder run examples/todo.py

Philosophy

Responder is intentionally familiar. If you know Flask, Falcon, Requests, or Starlette, you already know most of the ideas. The framework tries to make the simple thing feel natural, then keeps enough power nearby for real services: typed contracts, OpenAPI, auth, rate limiting, streaming uploads, websockets, and production middleware.

It is a passion project and a practical toolkit. It is especially good for personal services, internal tools, prototypes, teaching, research apps, and small APIs where clarity matters more than ceremony.

Documentation

The full guide lives at responder.kennethreitz.org.

• Quickstart
• Tour
• Examples
• Deployment
• Testing
• API reference
• Changelog

License

Apache-2.0.