loom.rest.model¶

Declarative REST interface model.

Defines the data structures that describe how UseCases are exposed over HTTP. No FastAPI or transport-specific code lives here — this module is the declaration layer; loom.rest.compiler validates and compiles it at startup and loom.rest.router_runtime binds it to FastAPI.

Usage:

class UserRestInterface(RestInterface[User]):
    prefix = "/users"
    tags = ("Users",)
    auto = True
    include = ("create", "get", "list", "update")
    routes = (
        RestRoute(use_case=CreateUserUseCase, method="POST", path="/"),
        RestRoute(use_case=GetUserUseCase, method="GET", path="/{user_id}"),
        RestRoute(use_case=ListUsersUseCase, method="GET", path="/"),
        RestRoute(
            use_case=UpdateUserUseCase,
            method="PATCH",
            path="/{user_id}",
            summary="Partial update user",
        ),
    )

Functions

_extract_model_type(cls)

Return the concrete model type from RestInterface[Model].

Classes

`RestApiDefaults`([pagination_mode, ...])	Global REST API defaults applied when interface or route level is unset.
`RestInterface`()	Base class for declarative REST interface definitions.
`RestRoute`(use_case, method, path[, summary, ...])	Declaration of a single HTTP endpoint bound to a UseCase.

class loom.rest.model.RestApiDefaults(pagination_mode=PaginationMode.OFFSET, allow_pagination_override=True, profile_default='default', allowed_profiles=<factory>)[source]¶

Bases: object

Global REST API defaults applied when interface or route level is unset.

Parameters:

pagination_mode (PaginationMode) – Default pagination strategy. Defaults to PaginationMode.OFFSET.
profile_default (str) – Default query profile name. Defaults to "default".
allowed_profiles (tuple[str, ...]) – Globally allowed profiles. Defaults to empty (no restriction imposed at global level).
allow_pagination_override (bool) – Whether query parameters may override the configured pagination mode. Defaults to True for backwards compatibility.

Example:

defaults = RestApiDefaults(
    pagination_mode=PaginationMode.CURSOR,
    profile_default="summary",
)

class loom.rest.model.RestInterface[source]¶

Bases: Generic[T]

Base class for declarative REST interface definitions.

Subclass to expose one or more UseCases under a common HTTP prefix. All class attributes have sensible defaults; override only what differs.

prefix¶

URL prefix for all routes in this interface (e.g. "/users").

Type:: str

tags¶

OpenAPI tags applied to every route.

Type:: tuple[str, …]

auto¶

When True, signals intent to use standard CRUD URL conventions.

Type:: bool

include¶

Whitelist of CRUD operation names to expose when auto=True. Accepted values: "create", "get", "list", "update", "delete". Empty tuple means all operations are allowed.

Type:: tuple[str, …]

routes¶

Explicit route declarations. Custom routes always override auto-CRUD routes with the same (method, path).

Type:: tuple[loom.rest.model.RestRoute, …]

pagination_mode¶

Default pagination strategy for list endpoints in this interface. Overridden per-route by RestRoute.pagination_mode.

Type:: loom.core.repository.abc.query.PaginationMode | None

profile_default¶

Default query profile for routes in this interface.

Type:: str

allowed_profiles¶

Profiles available to callers of routes in this interface.

Type:: tuple[str, …]

expose_profile¶

Whether this interface publicly accepts ?profile=... by default. Can be overridden per-route.

Type:: bool

allow_pagination_override¶

Whether list endpoints may switch pagination mode from query parameters by default.

Type:: bool | None

Example:

class OrderRestInterface(RestInterface[Order]):
    prefix = "/orders"
    tags = ("Orders",)
    auto = True
    include = ("create", "get", "list")
    routes = (
        RestRoute(use_case=CreateOrderUseCase, method="POST", path="/"),
        RestRoute(use_case=GetOrderUseCase, method="GET", path="/{order_id}"),
        RestRoute(use_case=ListOrdersUseCase, method="GET", path="/"),
    )

class loom.rest.model.RestRoute(use_case, method, path, summary='', description='', status_code=200, pagination_mode=None, allow_pagination_override=None, profile_default='', allowed_profiles=(), expose_profile=False)[source]¶

Bases: object

Declaration of a single HTTP endpoint bound to a UseCase.

All fields except use_case, method, and path are optional and override interface-level or global defaults when set.

Parameters:

use_case (type[UseCase[Any, Any]]) – Concrete UseCase class that handles this endpoint.
method (str) – HTTP method in uppercase ("GET", "POST", etc.).
path (str) – Path relative to the interface prefix. May include path parameters (e.g. "/{user_id}").
summary (str) – Short OpenAPI summary for the endpoint.
description (str) – Longer OpenAPI description.
status_code (int) – Default HTTP success status code. Defaults to 200.
pagination_mode (PaginationMode | None) – Override pagination strategy for this route. When None, inherits from the interface or global default.
profile_default (str) – Default query profile for this route. When empty, inherits from the interface or global default.
allowed_profiles (tuple[str, ...]) – Profiles that callers may request. When empty, inherits from the interface or global default.
expose_profile (bool) – Whether to expose ?profile= as a public query parameter for this route. Defaults to False.
allow_pagination_override (bool | None) – Whether callers may override the resolved pagination mode using query parameters. When None, inherits from the interface or global default.

Example:

RestRoute(
    use_case=UpdateUserUseCase,
    method="PATCH",
    path="/{user_id}",
    summary="Partial update user",
    status_code=200,
)