egress-proxies-operator/docs/plans-executions/2026-08-11-2152-discovery-api-docs.md

Execution: Discovery API documentation

Plan: 2026-08-11-2152-discovery-api-docs.md

• Step 1 — Write docs/api.md full API reference
• Step 2 — Add pointers in README and architecture.md

Step 1 — docs/api.md

Wrote the full reference: base URL (in-cluster FQDN + port-forward), bearer auth, error envelope, configuration table, all five routes with schemas, status codes and curl examples, the selection/cooldown semantics section, an end-to-end curl walkthrough, and the in-memory/single-replica caveats. All facts were taken from the code, not from memory of prior docs.

Worth noting: the doc explicitly calls out two things no earlier doc stated for clients — that a report without a target on a targetless lease creates a global cooldown (blocking the proxy for everyone), and that rate_limited and banned currently behave identically. Both came straight from internal/lease/store.go and are easy to trip over.

Step 2 — Pointers + verification

Added one-line links to the new doc in README's quickstart (above the curl block) and in docs/architecture.md §7. Verified the documented behavior against the tree rather than trusting the write-up:

go build ./... && go test -short ./internal/discovery/ ./internal/lease/

Both pass; a grep of server_test.go confirmed every documented status code and error code (invalid_ttl, invalid_query, invalid_result, no_match, unknown_lease, 201/204/401/404/409) is asserted by tests.

Worth noting: CHANGELOG entry deliberately deferred until the user confirms the docs read well, per the CHANGELOG convention's "once the user confirms it works" clause.