loom.rest.fastapi.app

FastAPI application factory.

create_fastapi_app() is the composition root that wires together the domain bootstrap result and REST interface declarations into a runnable FastAPI instance.

It is intentionally kept thin — all validation happens during RestInterfaceCompiler compilation (fail-fast at startup) and all request handling is delegated to bind_interfaces().

Usage:

result = bootstrap_app(
    config=cfg,
    use_cases=[CreateOrderUseCase, GetOrderUseCase],
    modules=[register_repositories],
)
app = create_fastapi_app(
    result,
    RouteSources(python=[OrderRestInterface]),
    observability_runtime=ObservabilityRuntime.noop(),
    title="Orders API",
    version="1.0.0",
)

Functions

_register_openapi_components(app, schemas)

Patch app.openapi to inject schemas into components.schemas.

_resolve_executor(result)

Return the application-scoped RuntimeExecutor registered at bootstrap.

_resolve_route_sources(routes, interfaces)

Resolve the deprecated interfaces alias into routes.

create_fastapi_app(result[, routes, ...])

Create a FastAPI application from a bootstrap result and REST interfaces.
loom.rest.fastapi.app.create_fastapi_app(result, routes=None, *, interfaces=None, observability_runtime=None, middleware=(), defaults=None, **fastapi_kwargs)[source]

Create a FastAPI application from a bootstrap result and REST interfaces.

Compiles all RestInterface declarations via RestInterfaceCompiler, binds each compiled route to the FastAPI instance, and returns the ready application.

Compilation is fail-fast: any structural error (missing use-case plan, duplicate route, missing prefix) raises InterfaceCompilationError before the app starts accepting requests.

Parameters:

  • result (BootstrapResult) – Fully initialised BootstrapResult from bootstrap_app().

  • routes (RouteSources | None) – Which interfaces to mount and from which origin — see RouteSources. routes.config compiles after routes.python, deterministically; a (method, path) collision between the two aborts naming both — neither side takes precedence. routes.disabled is applied to routes.python before the merge, so a disabled Python route can be redeclared in routes.config without colliding with itself; an entry matching no Python-declared route aborts startup instead of doing nothing. Required unless interfaces is given instead.

  • interfaces (Sequence[type[RestInterface[Any]]] | None) – Deprecated keyword-only alias for routes=RouteSources(python=interfaces). Kept only so code written before RouteSources existed keeps working when it called create_fastapi_app(result, interfaces=[...]) — every published example did; emits a DeprecationWarning naming routes as the replacement. Mutually exclusive with routes.

  • observability_runtime (ObservabilityRuntime | None) – Shared runtime used to emit lifecycle events around each request.

  • middleware (Sequence[Any]) –

    ASGI middleware classes to register on the application. Added in declaration order (first = outermost wrapper). Accepts any class compatible with FastAPI.add_middleware. Example:

    from loom.rest.middleware import TraceIdMiddleware
from loom.prometheus import PrometheusMiddleware

app = create_fastapi_app(
    result,
    RouteSources(python=[...]),
    observability_runtime=ObservabilityRuntime.noop(),
    middleware=[TraceIdMiddleware, PrometheusMiddleware],
)

  • defaults (RestApiDefaults | None) – Global REST API defaults (pagination mode, profile policy). Falls back to RestApiDefaults when not provided.

  • **fastapi_kwargs (Any) – Additional keyword arguments forwarded to the FastAPI constructor (e.g. title, version, docs_url).

Returns:

Configured fastapi.FastAPI instance ready to serve requests.

Raises:
Return type:

fastapi.FastAPI

Example:

app = create_fastapi_app(
    result,
    RouteSources(python=[UserRestInterface, OrderRestInterface]),
    defaults=RestApiDefaults(pagination_mode=PaginationMode.CURSOR),
    observability_runtime=ObservabilityRuntime.noop(),
    title="My API",
    version="2.0.0",
)