# ADR-0002: Establish the REST API Foundation

Status: Accepted  
Date: 2026-04-27

## Context

The first HTTP slice needed stable versioning, response conventions, dependency composition, and server lifecycle behavior.

## Decision

- Place REST routes under `/api/v1`.
- Expose build metadata through `GET /api/v1/version`.
- Return resource bodies directly for successful requests.
- Return errors as `{"error":{"message":"..."}}` with optional diagnostic fields.
- Use `internal/app.Bootstrap` to construct runtime dependencies and return `app.WebApp`.
- Register public and protected routes in separate server functions.
- Stop accepting new requests during shutdown and allow in-flight requests to finish.

## Consequences

- Future REST endpoints share one version boundary and response convention.
- `app.WebApp` provides the services and metadata required by route setup.
- HTTP lifecycle behavior stays in `internal/server`.