mygo/docs/server/decisions/0002-rest-api-foundation.md

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.