master/docs/004-versioned-http-api.md

004 Versioned HTTP API

Context

• The template needs explicit API versioning and an HTTP boundary that can be replaced later.
• FastAPI is the initial framework, but it must not become a hard dependency for core logic.

Decision

• Place HTTP transport code under adapter/http/fastapi/.
• Mount routers under /api/v1 and keep version-specific routers in routers/v1/.
• Map HTTP requests to usecase calls through thin dependencies and handlers only.
• Keep framework-specific request and response models in the HTTP adapter layer.

Consequences

• New API versions can be introduced without changing usecase contracts.
• Replacing FastAPI means rewriting only the HTTP adapter.
• Domain and usecase layers remain free from transport concerns.