Connect by JBRH Open Connect

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 What this means
Audience
both, developer
Last verified
Product version
6.3.2

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

Where Connect uses it#

Place in ConnectWhat it does there
backend/app/main.pyThe application object, the middleware stack, the audience allowlist (customer_safe) and the session cookie
backend/app/api.py and the *_api.py modulesThe 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.pyThe /api/v1 door: API keys, plan gates, the error envelope and the OpenAPI document at /api/v1/openapi.json
Starlette importsmain.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.
  • Interactive API docs pages are not published. The public reference is the static rendering under /developers/.

Licence, cost and versions#

QuestionAnswer
LicenceFastAPI: MIT. Starlette: BSD-3-Clause
CostNone
Versionfastapi>=0.115. Starlette arrives as FastAPI's dependency, at the version that FastAPI release requires
CompatibilityPydantic 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#

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.