Jan Novak
09845e4eaf
Full client-facing reference: auth, all routes with schemas and curl examples, selection/cooldown semantics, caveats. README and architecture.md link to it. Co-Authored-By: Claude <noreply@anthropic.com>
39 lines
1.7 KiB
Markdown
39 lines
1.7 KiB
Markdown
# Execution: Discovery API documentation
|
|
|
|
Plan: [2026-08-11-2152-discovery-api-docs.md](../plans/2026-08-11-2152-discovery-api-docs.md)
|
|
|
|
- [x] Step 1 — Write `docs/api.md` full API reference
|
|
- [x] 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:
|
|
|
|
```sh
|
|
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.
|