OpenAPI spec for the WaveHouse API + machine-readable discovery (/.well-known/api-catalog) #302

Activity

1. EricAndrechek

   added

   enhancementNew feature or requestNew feature or request

   area/apiHTTP handlers, routing, middlewareHTTP handlers, routing, middleware

   area/sdkTypeScript SDK (clients/ts/)TypeScript SDK (clients/ts/)

   area/docsDocumentation, site/, READMEDocumentation, site/, README

   on Jun 8, 2026
2. github-project-automation

   added this to WaveHouse Task Boardon Jun 8, 2026
3. github-project-automation

   moved this to Backlog in WaveHouse Task Boardon Jun 8, 2026
4. coderabbitai commented on Jun 8, 2026

   

   coderabbitaibot

   on Jun 8, 2026 – with coderabbitai

   More actions

   🔗 Related PRs

   #123 - fix(api): drop CORS credentials + skip same-origin decoration [merged]
   #137 - feat(deploy): local dev o11y stack (#121) [merged]

   ---

   📝 Issue Planner

   _{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

   • Create Plan

   ---

   🧪 Issue enrichment is currently in open beta.

   You can configure auto-planning by selecting labels in the issue_enrichment configuration.

   To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

   issue_enrichment:
     auto_enrich:
       enabled: false

   💬 Have feedback or questions? Drop into our discord!
5. EricAndrechek

   added a commit that references this issue on Jun 9, 2026

   fix(docs): real per-page Last-updated dates + open AI content signals (…

   ...

   60fed15
6. EricAndrechek commented on Aug 13, 2026

   

   EricAndrechek

   on Aug 13, 2026

   MemberAuthor

   More actions

   One consumer worth designing for explicitly, because it adds a few requirements the current acceptance list doesn't cover: a gateway or reverse proxy fronting several WaveHouse deployments of differing versions, deriving its own behavior from each deployment's spec.

   That's the generalization of the "self-hosted WaveHouse self-describes at its own origin" bullet already in the Why — but a fronting system needs more from the document than a human or a one-deployment SDK does. Everything below is a gap I hit reading the current router and docs, and each one is the difference between "the proxy derives this" and "the proxy hardcodes a table that silently goes stale on upgrade."

   Stable operationIds, treated as API surface. Anything mapping operations onto its own handlers, permissions, or tools needs a stable key — path+method is workable but brittle when a path changes shape. Worth adding to the acceptance list, and worth saying in the docs that renaming one is a breaking change, since downstream mappings are invisible from here.

   Express the admin/non-admin split in the spec. Right now that gate is a router fact: RequireAdmin wraps /v1/admin/*, and also /v1/schema, /v1/schema/refresh, and /v1/dlq/stats. So the /v1/admin/ prefix is not a reliable signal for whether an operation is privileged — which is exactly the trap a fronting proxy falls into, because path-shape is the only thing it can see today. Encoding the gate (a distinct security requirement, a scope, or an x- extension) lets a proxy derive authorization tiers instead of guessing, and means a new privileged endpoint landing outside the prefix doesn't silently widen what that proxy allows. This is the single most valuable addition on this list.

   Mark the operational endpoints. The reverse-proxy guide already recommends keeping /livez//readyz//healthz internal — a public /readyz turns each hit into a ClickHouse Ping — and exposing only /v1/health. If the spec marks which operations are operational rather than API surface, a fronting proxy can exclude them automatically instead of maintaining its own denylist, which is the thing that goes stale precisely when the deployment is upgraded.

   info.version tied to the build. So a consumer can cache the derived surface per engine version and invalidate on upgrade. Without it, cache invalidation is guesswork against a moving target.

   State whether discovery itself is authenticated. /openapi.json and /.well-known/api-catalog should be explicitly unauthenticated (or explicitly not). If learning the surface requires a credential, the discovery story doesn't work for a fronting system — and arguably not for the agent/crawler cases either, which is the motivating use here.

   Document the two non-obvious response shapes on /v1/admin/query. It returns ClickHouse's FORMAT JSON envelope unwrapped — just the data array — rather than the envelope itself; and an inline FORMAT override (SELECT 1 FORMAT CSV) bypasses default_format=JSON entirely and returns a non-JSON body with the upstream Content-Type. Both are correct and deliberate, and both are the kind of thing a spec-generated client gets wrong by assuming a uniform JSON response. Worth pinning in the schema rather than leaving to the handler comments.

   Decide how /v1/stream is represented. SSE doesn't model as an ordinary response, and a consumer generating a typed method from the spec will produce something broken unless the document says text/event-stream and marks it as streaming. Also relevant: it accepts the ?token= query credential the other endpoints don't need, so its security differs.

   None of these change the recommendation between A / C / D — they're requirements on the resulting document whichever way it's produced. If it helps, the ones I'd put in acceptance are the operationIds, the admin-gate encoding, and the operational-endpoint marking; the rest are documentation quality.