# FastAPI and Starlette

FastAPI is the Python web framework every Connect route is written in. It sits on Starlette, which supplies the request, response and middleware machinery, and uses Pydantic to validate input. Connect has two audiences: the Owner and a customer. Their routes are separate routers on one application, and middleware decides which audience may call which path.

- **Status:** Reference
- **Audience:** both, developer
- **Last verified:** 2026-11-02
- **Canonical:** https://connectbyjbrh.com/docs/technology/fastapi/

## What it is

FastAPI is an open-source framework created by Sebastián Ramírez and first released in 2018. It declares an endpoint as an ordinary Python function with type hints. The framework reads those hints to parse and validate the request and to document the endpoint in OpenAPI.

Starlette, from the Encode project, is the ASGI toolkit underneath. It handles routing, requests, responses, middleware, static files and background tasks. FastAPI adds dependency injection, validation and documentation on top.

**Category** — Python web framework (ASGI)
**Built on** — Starlette and Pydantic
**Version in Connect** — `fastapi>=0.115` (a floor in `requirements.txt`)
**Official site** — [fastapi.tiangolo.com](https://fastapi.tiangolo.com/)

## Where Connect uses it

| Place in Connect | What it does there |
|---|---|
| `backend/app/main.py` | The application object, the middleware stack, the audience allowlist (`customer_safe`) and the session cookie |
| `backend/app/api.py` and the `*_api.py` modules | The routers: one door per area, each calling a shared module, so both audiences run one body of code |
| `backend/app/saas_registry.py`, `saas_http.py` | The `/api/v1` door: API keys, plan gates, the error envelope and the OpenAPI document at `/api/v1/openapi.json` |
| Starlette imports | `main.py`, `workspace_data_api.py`, `public_catalog_api.py`: middleware and responses below FastAPI's level |

## How it connects

1. Caddy forwards the request to Uvicorn on `127.0.0.1:8420`
2. Starlette middleware: the session, the audience allowlist and the workspace context
3. FastAPI routing picks the handler, and Pydantic validates the body
4. The handler calls the shared module, and SQLAlchemy runs the queries inside the workspace scope
5. The response goes back as JSON, a page, or a server-sent event stream

## Benefits and limits

What it gives Connect:

- Validation and documentation come from one declaration. The `/api/v1` OpenAPI document is generated from the code that serves it, so it cannot drift from the routes.
- `async` handlers suit Connect's provider calls, and plain functions run in a thread pool.
- Middleware is the natural place for a rule that must apply to every request, such as the audience allowlist.

Where it stops, and what Connect does about it:

- A rule placed in middleware reaches every request, so `main.py` is a wide-radius file. A change there runs the whole regression set.
- Blocking code inside an `async def` stalls the event loop for everyone. Slow synchronous work belongs in a plain `def` (run in the thread pool) or a background worker.
- The framework validates shape, not meaning. Business rules such as plan limits and approval live in Connect's own modules.

## Security and privacy

- The audience boundary is enforced before routing. A customer session calling an Owner path is refused in middleware, whatever the handler does.
- Session cookies are set by one function (`main._set_session_cookie`) with the secure flags. See [sessions and cookies](/docs/technology/sessions-cookies/).
- Interactive API docs pages are not published. The public reference is the static rendering under `/developers/`.

## Licence, cost and versions

| Question | Answer |
|---|---|
| Licence | FastAPI: MIT. Starlette: BSD-3-Clause |
| Cost | None |
| Version | `fastapi>=0.115`. Starlette arrives as FastAPI's dependency, at the version that FastAPI release requires |
| Compatibility | Pydantic v2 (`pydantic>=2.7`), Python 3.12 |

## Troubleshooting

**A tenant gets 403 where the Owner gets 200** — Almost always the allowlist in `main.py` or `tenantAdapt` in the browser, not the feature. Run `python tools/route_map.py <path>` to see which audience may call it.
**422 Unprocessable Entity** — Pydantic rejected the body. The response says which field and why.
**Every request slows down at once** — Something blocking is running on the event loop. Look for a synchronous network call inside an `async def`.

## Official references

- [FastAPI documentation](https://fastapi.tiangolo.com/)
- [Starlette documentation](https://www.starlette.io/)
- [ASGI specification](https://asgi.readthedocs.io/)

## Questions

### Why are there two routers for one feature?

Connect serves the Owner and customers from one codebase. The rule is one body, two doors: the behaviour lives in one module and each audience's router adds only the route. That way a fix reaches both.

### Is the API documentation generated by FastAPI?

The `/api/v1` OpenAPI document is. The interactive pages FastAPI can serve are not exposed. The document is rendered statically for developers instead.

## Related

- [Uvicorn, the ASGI server](https://connectbyjbrh.com/docs/technology/uvicorn/)
- [Pydantic data validation](https://connectbyjbrh.com/docs/technology/pydantic/)
- [REST](https://connectbyjbrh.com/docs/technology/rest/)
- [Authorisation models](https://connectbyjbrh.com/docs/technology/authorization-models/)

## What this page is based on

- `backend/app/main.py`
- `backend/app/saas_registry.py`
- AGENTS.md §3
- https://fastapi.tiangolo.com/
