lbedner/aegis-stack/add-api-endpoint

Add API endpoint

Add an HTTP route to the FastAPI backend. Endpoints live under app/components/backend/api/ and are mounted by a single registration file, so a route is not reachable until it is both defined and registered.

When to use

Use when adding or changing an HTTP route the backend serves.

Do NOT use for background work (that is a job, not a request) or for scheduled work. Do NOT hand-add a whole new service or component this way; use the aegis CLI for that.

Files that change

• app/components/backend/api/: endpoint modules live here. Add <name>.py

with an APIRouter, or a <name>/router.py package for a group of routes.

• app/components/backend/api/routing.py: register the router here (import it

and mount it with app.include_router(...)).

• app/components/backend/api/deps.py: shared FastAPI dependencies; add one

here if the endpoint needs a reusable dependency.

• app/components/backend/api/health.py: the health surface; wire a check if

the endpoint fronts a new subsystem.

• tests/api/: add test_<name>_endpoints.py.

Procedure

1. Write the failing test first in tests/api/test_<name>_endpoints.py, driving

the route through the test client. Confirm it fails for the right reason (the route does not exist yet).

1. Define the request and response schemas as Pydantic or SQLModel classes.
2. Create the router module in app/components/backend/api/ with an

APIRouter() and the route handlers as async def.

1. Register the router in app/components/backend/api/routing.py: import it and

call app.include_router(...).

1. Add any reusable dependency to app/components/backend/api/deps.py, and wire

a health check in health.py if the endpoint fronts a new subsystem.

1. Run the gates and fix anything red.

Gates

• make check: lint, typecheck, and test.

Pitfalls

• A router that is defined but never registered in routing.py returns 404; the

registration step is what makes the route reachable.

• Route handlers are async def; a blocking call inside one stalls the event

loop and slows every request, so use the async client or run blocking work off the loop.

• Returning a raw dict instead of the declared response model skips validation

and drifts the response from its schema.