hex-restapi-endpoint
Use when adding or changing one REST route, or creating a resource's router file `restapi/routers/<resource>.py` — thin routes over application handlers, a route that carries a file, dishka handler in
SKILL.mdplugins/pyhouse-hex/skills/hex-restapi-endpoint/SKILL.md
GitHubHex — REST API Endpoint
Produces one HTTP endpoint for one resource. Routers grow incrementally — this skill adds one route at a time. A "router file" exists once per resource; subsequent endpoint additions extend it.
Read the sibling CONTRACTS.md in this skill's own directory before choosing what a route advertises
in responses=error_responses(...). It carries the per-operation code sets and the helper the
decorator draws on; only SKILL.md is loaded automatically.
When to use vs. neighbours
- One new endpoint or modification of an existing one, including one that carries a file → this skill.
- Pydantic request/response schemas this route maps to and from →
hex-restapi-schema. - The
responses=error_responses(...)declaration and which codes belong in it → this skill, in the siblingCONTRACTS.md. - Defining a new error class, and boundary translation →
exception-catalog; the status it answers with →hex-restapi-app'sSTATUS_BY_ERROR, needed only where it differs from its parent's. - Attaching an auth dependency to a route, and the
401/403that follow it →hex-restapi-auth. - The shell this router registers into —
restapi/main.py, its middleware, and the registry for a status a middleware introduces →hex-restapi-app. - The composition root that binds the handler this route injects →
hex-wiring. - Testing this route through the real app →
hex-test-restapi-endpoint; the OpenAPI and app-construction properties discovered across all routes →hex-test-app-invariants. - Route, module and helper identifiers →
naming;__all__and the router export →python-packaging.
Template(s) — FastAPI router, dishka-injected
File location
src/myapp/restapi/routers/foos.py
One router file per resource holds all of that resource's endpoint functions; the file declares the APIRouter, defines each endpoint function (ordered per Route ordering), and is registered once in src/myapp/restapi/main.py via app.include_router(...). The skeleton below is the whole-file shape; an endpoint function is the per-route shape that follows it.
route_class=DishkaRoute on the router is what injects every FromDishka[...] parameter below it, so it is declared once per file and no route carries an injection decorator.
Skeleton — router file
from typing import Annotated
from uuid import UUID
from dishka.integrations.fastapi import DishkaRoute, FromDishka
from fastapi import APIRouter, Query
from fastapi.responses import Response
from myapp.application.foos import (
CreateFooCommand,
CreateFooHandler,
DeleteFooCommand,
DeleteFooHandler,
GetFooHandler,
GetFooQuery,
ListFoosHandler,
ListFoosQuery,
UpdateFooCommand,
UpdateFooHandler,
)
from myapp.domain.foos import FooListFilter
from ..schemas import (
FooCreateRequest,
FooListResponse,
FooResponse,
FooUpdateRequest,
error_responses,
)
__all__ = ["router"]
_MAX_PAGE_SIZE = 100
router = APIRouter(prefix="/foos", tags=["foos"], route_class=DishkaRoute)
The skeleton imports what the CRUD routes below use.
The route templates below are auth-free — every route in an app that declares no auth, and the
public routes of one that does. An authenticated route is derived by hex-restapi-auth's ROUTES.md.
list (paginated read) — pagination shape mirrors hex-domain-model
A page size is always bounded and always defaulted — an unbounded limit lets one request ask for the whole table. The ceiling is the app's decision and a named module-level constant in the router file (_MAX_PAGE_SIZE in the skeleton), because Query(...) bounds are evaluated when the route function is defined and cannot be injected per request; an app picks a ceiling its list query can serve in one round trip. The default is the filter's (hex-domain-model), read off FooListFilter.limit — a class-level default only an unslotted dataclass has — so the number is stated once, and the route passes limit to the filter explicitly. ge=1 on the page size and ge=0 on the offset are not tunable — a zero-row page and a negative offset are meaningless at any ceiling.
@router.get("", response_model=FooListResponse, responses=error_responses(422))
async def list_foos(
handler: FromDishka[ListFoosHandler],
limit: Annotated[int, Query(ge=1, le=_MAX_PAGE_SIZE)] = FooListFilter.limit,
offset: Annotated[int, Query(ge=0)] = 0,
) -> FooListResponse:
result = await handler.execute(
ListFoosQuery(filter=FooListFilter(limit=limit, offset=offset)),
)
return FooListResponse(
items=[FooResponse(id=foo.id, name=foo.name, note=foo.note) for foo in result.items],
total=result.total,
limit=limit,
offset=offset,
)
Every filter field a caller may set is a query parameter of the same name and type — a sort is its
domain enum, which answers an unknown value with the input-validation status — and each is passed to the
filter; a filter field no parameter reaches is dead down to the repository. Where they take the signature
past python-toolchain's positional cap, the query parameters and the auth dependency are keyword-only,
after a bare *.
A filter that pages by cursor instead (hex-domain-model, filter rule 5) takes a cursor query parameter in place of offset, passes it into the filter, and returns next_cursor in place of total/offset; FooListResponse (hex-restapi-schema) matches whichever shape the filter uses.
get (single read)
@router.get("/{id}", response_model=FooResponse, responses=error_responses(404, 422))
async def get_foo(
id: UUID,
handler: FromDishka[GetFooHandler],
) -> FooResponse:
foo = await handler.execute(GetFooQuery(id=id))
return FooResponse(id=foo.id, name=foo.name, note=foo.note)
create (with post-write read-back)
@router.post(
"",
response_model=FooResponse,
status_code=201,
responses=error_responses(409, 422), # 409 only where Foo has a unique field
)
async def create_foo(
body: FooCreateRequest,
handler: FromDishka[CreateFooHandler],
get_handler: FromDishka[GetFooHandler],
) -> FooResponse:
new_id = await handler.execute(
CreateFooCommand(name=body.name, note=body.note),
)
foo = await get_handler.execute(GetFooQuery(id=new_id))
return FooResponse(id=foo.id, name=foo.name, note=foo.note)
update (PATCH with read-back)
@router.patch(
"/{id}",
response_model=FooResponse,
responses=error_responses(404, 409, 422), # 409 only where Foo has a unique field
)
async def update_foo(
id: UUID,
body: FooUpdateRequest,
handler: FromDishka[UpdateFooHandler],
get_handler: FromDishka[GetFooHandler],
) -> FooResponse:
await handler.execute(UpdateFooCommand(id=id, name=body.name, note=body.note))
foo = await get_handler.execute(GetFooQuery(id=id))
return FooResponse(id=foo.id, name=foo.name, note=foo.note)
delete (204)
@router.delete(
"/{id}",
status_code=204,
responses=error_responses(404, 422),
)
async def delete_foo(
id: UUID,
handler: FromDishka[DeleteFooHandler],
) -> Response:
await handler.execute(DeleteFooCommand(id=id))
return Response(status_code=204)
409 joins the set only where another aggregate can reference a Foo, so a delete can find it still in
use.
Route ordering — FastAPI declaration order
FastAPI resolves a request against the routes in declaration order, which makes the reachability
obligation (rule 13) a property of where a route sits in the file. A literal sibling of /{id} —
/search, or any other collection-level action — declared after /{id} is captured by it: the
literal matches {id}, fails its UUID validation, and the request answers 422 before any handler
runs; the literal route is never reached.
Declare every literal collection-level path above the /{id} routes, whatever its method. When
extending an existing router file, place a new literal route above the get / update / delete
routes for /{id}.
A framework that resolves by specificity instead has no such ordering to get wrong: the obligation is unchanged, and nothing in the file's layout can violate it.
Other bindings
dependency-injector. Everything above the signature is unchanged — decorators, status codes, route ordering, the no-try/exceptrule, read-back. What changes is that the route takesrequest: Requestback and, inside the body, reaches the composition root hanging off the app state and calls the binding whose attribute name is the snake_case form of the handler class. That spelling becomes a contract withhex-wiringthat nothing enforces. The router then needs noroute_class.- A route-scoped injection decorator instead of the router's route class. Where a route cannot go through the router — a websocket handler, or a
Dependsfactory such as the auth dependency inhex-restapi-auth— the sameFromDishka[...]parameter is injected by decorating that function with@inject. Use it only there; a decorator on an ordinary HTTP route means the router is missing itsroute_class.
Rules
Router file
- One module per resource. File naming follows
naming. - Only
routeris public; export mechanics followpython-packaging. prefixis the resource word, plural, as the file name has it — one casing for every path, kebab-case unless the API already has another (/foo-bars).tags=[...]echoes the resource word.
Parameter order (load-bearing for readability, not FastAPI)
- Parameters go in one order — path parameters (
id: UUID), then body (body: FooCreateRequest), then injected handlers (handler: FromDishka[CreateFooHandler]), which carry no default and so must precede every defaulted parameter anyway, then query parameters with defaults (limit,offset), and the auth dependency last (_oruser) when the route has one —hex-restapi-auth.
Status codes (defaults)
- The operation fixes the success status and the return type.
| Operation | Decorator | Return type |
|---|---|---|
GET list |
default 200 | FooListResponse |
GET single |
default 200 | FooResponse |
POST create |
status_code=201 |
FooResponse (read-back) |
PATCH update |
default 200 | FooResponse (read-back) |
DELETE |
status_code=204 |
Response(status_code=204) |
For 204 endpoints, the function return annotation is -> Response and the body is return Response(status_code=204). Do not return None — the 204 then lives in the decorator alone, and a decorator that loses its status_code=204 answers 200 with a JSON null body instead of failing visibly.
What the route advertises
The per-operation code sets and the helper are in the sibling CONTRACTS.md; registering a middleware's status is hex-restapi-app's.
- Routes only advertise. A route never builds an error response itself: one translator owns the error body's shape, and a hand-built body is the copy that drifts from it. The error catalogue and boundary translation are
exception-catalog's; logging ispython-logging's. - Advertise exactly what the route can produce. The set follows from the operation — which domain exceptions its handler can raise, which middleware sits in front of it, and whether it takes any validated input. A code that cannot occur is removed — an auth code follows the auth dependency (
hex-restapi-authrule 7); a code that can occur and is missing makes the published document wrong in the direction clients notice last. - Never hand-write the advertisement mapping —
responses={404: {...}}typed out at the decorator. Always go through the helper, because the helper is what checks the code against the set of codes something can actually produce; a hand-written entry is the one path by which a status nothing raises reaches the document, and the helper rejects a status nothing maps or registers (hex-restapi-app). - A route taking any validated input advertises the input-validation status. Path parameter, query parameter, filter, pagination or body — any of them can be rejected before the handler runs, so the document must say so. It is any-input validation, not body validation: a lone
{id}produces it, and only a parameterless, body-less route omits it. Where the framework publishes a response of its own for that status, the decorator still names it: the framework's entry describes the framework's error body, not the one the app sends.
Handler injection
handler: FromDishka[ListFoosHandler],
- The handler is injected per request, by its concrete class — never by binding name, never at module level (
hex-wiring;hex-architecturerule 8). The concrete class is also what gives the type checkerexecute, and a module-level resolution would defeat the per-test composition root. - A response needing fields the command's result does not carry is a read-back through the matching query handler, or the query's result DTO is extended (
hex-application). For create/update with read-back, takehandlerandget_handleras two separate injected parameters with distinct names.
Route reachability
- Every route the file declares must be the one a matching request actually reaches. A path a more general sibling can also match is dead, and it fails silently — the wrong handler runs and answers, so there is no routing error to see. Where the framework resolves paths by a rule the file's own layout can violate — declaration order, a first-match table — satisfying that rule is part of writing the route. The FastAPI spelling is under
### Route orderingabove.
What never goes in a route
- No
try/except. Domain exceptions propagate to the central error handler. The only sanctioned exception is rule 21. - No logging. Which layer logs is
hex-architecture's; the event's shape ispython-logging's. - No business logic, no policy checks, no domain construction beyond mapping body→command. Constructing the entity is the handler's job.
- No infrastructure imports. Only
application/*anddomain/*types. - No
Dependsfactories at module level. The auth pair is the one exception, andrequire_roleis still called inline at each route (hex-restapi-authrule 5).
Routes that carry a file — only where the resource has one
- The route moves the bytes and does nothing else with them. An upload's bytes go onto the
command unparsed; a download's bytes, or its stream, come back from the handler untransformed.
Parsing, generating and storing them are the handler's and an adapter's (
hex-application,hex-capability-adapter); the route never writes to or serves from a path on disk. - An upload is bounded before the framework reads it. The framework reads the whole body before the route runs, so the bound sits ahead of it — the app's request-size middleware on the declared length, whose status the route then advertises, or the edge; a bounded read in the route only keeps an over-size file out of memory.
- A body part the framework does not validate is validated in the route, and its rejection translated. A JSON document carried in a form field beside a file is parsed with its wire model, and the model library's error becomes the catalogue's validation class, naming the fields by location and never echoing a value. This is rule 14's one exception; a JSON-only route never needs it.
- A binary response states its media type, and the published document describes it as that type,
never as a JSON model. A header a cross-origin page must read is exposed where the app declares
CORS (
hex-restapi-app).
Inlined typing / import rules
Annotatedfromtyping;UUIDfromuuid.DishkaRoute,FromDishkafromdishka.integrations.fastapi.Requestis not imported unless a route genuinely reads the raw request; reaching the composition root is not such a reason.APIRouter,Queryfromfastapi;Responsefromfastapi.responses.- Application handlers imported through the subpackage (
from myapp.application.foos import ...) — seepython-packagingfor the collapsed-import convention. error_responsesfrom..schemas.- Full annotations on every parameter and on the return type; no
from __future__ import annotations(python-style).
Package wiring
When the router file is new
After adding the route(s), register the router in src/myapp/restapi/main.py: the import goes at the top of the file, and the app.include_router(...) line between register_error_handlers(app) and setup_dishka(...) (hex-restapi-app):
from .routers.foos import router as foos_router
app.include_router(foos_router)
restapi/routers/__init__.py stays empty — every route module exports a colliding router
(hex-architecture, entrypoint carve-out).
Hard stops
- A route is asked to catch a domain exception and translate it → stop, use
hex-restapi-app: a different status is an entry inSTATUS_BY_ERROR, a new failure a class underexception-catalog. - A third auth dependency type, or any other auth machinery, is proposed → stop, use
hex-restapi-auth; this skill declares the codes a route advertises, not the auth layer behind them. - Asked for the request or response models a route maps → stop, use
hex-restapi-schema.