api-layer · diff

git:20260507.fc5df68 to git:20260510.9ae35e3

1 added, 1 removed. Audit A to A.

---

description: Optional HTTP gateway, OpenAPI spec source of truth

globs: external/httpserver/**/*.go

alwaysApply: false

---

# HTTP API layer (`external/httpserver`)

- - Built only with **`-tags http`**. Handlers are registered in **`Server.New`** in **`server.go`**.

+ - Built with **`-tags http`**. SPA root **`/`** (`go:embed` from **`external/ui`**) links only when you add **`tags=ui`** with **`go build -tags=http,ui`** (see **`mountEmbeddedSPARoot`** splits in **`spa_embed_ui.go`** / **`spa_no_ui.go`**). Handlers are registered in **`Server.New`** in **`server.go`**.

- **`openapi.go`** builds the served OpenAPI 3 document (`openAPISpec`). It is the **programmatic** spec; it must describe the same paths, methods, parameters, schemas, and response shapes as the live handlers.

- After any change to routes or externally visible request or response behavior, update **`openAPISpec`** and extend **`server_test.go`** (or add tests) under the **`http` build tag.

- User-facing narrative lives in **`docs/http-api.md`**; keep it aligned when endpoints or semantics change.

## References

@workflow.mdc

@docs/http-api.md

@external/httpserver/server.go

@external/httpserver/openapi.go