Examples

The examples/ directory is the quickest way to see Responder’s pieces working together. Each file is a small app you can run directly, poke with curl, and copy from when you need the same pattern in your own service.

Running an Example

From an installed environment, run an example with the Responder CLI:

$ responder run examples/helloworld.py

Then call it from another terminal:

$ curl http://127.0.0.1:5042/hello
hello, world!

When you are working from a checkout of this repository, prefix the command with uv run so the project environment is used:

$ uv run responder run examples/rest_api.py

Most examples expose interactive OpenAPI docs at /docs. Open http://127.0.0.1:5042/docs in a browser after starting one of the API examples.

Where to Start

helloworld.py

The smallest useful app: one index route, one route parameter, and no sessions. Start here if you want to see the request/response shape.

rest_api.py

A compact book catalog with Pydantic input models, response models, OpenAPI metadata, resp.created(), resp.no_content(), and resp.problem().

todo.py

The practical all-around example: typed input, filtering, bearer-token auth, named auth policies, request IDs, and richer OpenAPI examples.

atelier.py

The contract-test fixture. It is intentionally polished because the test suite validates its generated OpenAPI document and drives a generated client against it.

Focused Patterns

user.py

A smaller typed CRUD-style API for users.

shortlinks.py

Redirects, conflict responses, generated short codes, and click tracking.

webhooks.py

Raw-body signature verification before JSON validation, useful for Stripe-style webhook receivers.

fortunes.py

A local-command wrapper that turns the fortune CLI into an API and reports command failures as problem-details responses. Install the fortune command, or set FORTUNE_COMMAND to a compatible command.

lifespan.py

Startup and shutdown work with an async lifespan context manager.

sse_stream.py

Server-Sent Events with heartbeat support and a tiny browser page.

websocket_chat.py

A minimal WebSocket chat room with a shared in-memory hub.

marimo_mount.py

Mounts a marimo notebook under /notebooks/ while keeping normal Responder routes and OpenAPI docs on the parent app. Install marimo first:

$ uv pip install marimo

tarot.py

A larger read/browse/deal API with Pydantic models and repeatable example data.

Testing Examples

Several examples expose a create_api() function so tests can build a fresh app with a fake store or fake external dependency. For example, examples/fortunes.py accepts a fortune_reader callable, which lets the test suite verify the API contract without depending on the local fortune binary.

That shape is a good habit for your own apps too: keep route wiring in create_api(), pass real dependencies in production, and pass fakes in tests.