API Patterns
API Patterns
Section titled “API Patterns”Overview
Section titled “Overview”Integrations should use the same public application boundary as the browser unless a deployment-specific integration contract says otherwise. The public API model is scoped, authenticated, JSON-oriented, and job-aware.
How it works
Section titled “How it works”Short operations return a normal response. Long-running operations return or create a job that can be observed through job status endpoints or the UI. Requests that affect tenant data must include the correct environment and tenant context.
The Android app follows the same rule but uses a narrower mobile viewer surface. Dashboard and alert reads are supported; source editing, dashboard authoring, and administration remain web workflows.
Analytical query boundary
Section titled “Analytical query boundary”The analytical query surface is a row-bounded read protocol. It accepts one safe, read-only statement, requires explicit environment and tenant scope, executes with a read-only database role and transaction, and caps the returned rows. A consistency preference may select the primary or an eligible replica, but it never raises the database privilege. Replica routing is an experimental read tier, not an HA or automatic failover guarantee.
Query Workbench previews use the dedicated
SQL Query Stream v1 route. The request remains
JSON, while the response is a strict sequence of four-byte big-endian lengths and UTF-8
JSON records. A hello record declares the byte and batch limits, schema precedes rows,
and exactly one terminal record reports a complete, truncated, or error outcome.
Implementation has landed; local and beta certification remain open.
Row batches are provisional until that terminal is validated. A complete or
truncated terminal commits the bounded preview; an error terminal, malformed
stream, or terminal-less EOF discards every provisional row.
The v1 path reads bounded database cursor batches and waits for downstream write
capacity before requesting another batch. The application edge relays the body
incrementally. The browser transfers one chunk at a time to a dedicated parser Worker,
which owns framing, UTF-8 decoding, JSON parsing, protocol validation, and row
reconstruction. Before structured-clone it replaces deep structured/bytea cells and
oversized scalar text with bounded preview descriptors. The browser main thread still
owns request lifecycle, preview-state integration, and rendering, so this architecture
is not a zero-main-thread-work or general responsiveness guarantee; Worker-side
JSON.parse expansion is still part of runtime certification. Initial headers and
Worker credits each have five-second phase deadlines, while the healthy body uses a
40-second no-byte watchdog rather than a wall-clock cap. Rejected or aborted bodies
have a separate five-second cleanup-settlement deadline.
The existing compatibility JSON wire contracts remain unchanged. They admit a memory reservation before database checkout, guard PostgreSQL backend frames and aggregate row bytes, and buffer only serialized response bytes covered by that grant. They do not provide the v1 terminal or database-to-network backpressure contract. Integrations handling bulk or very wide data must use a purpose-built export workflow rather than either generic query route.
The keyset-window variant stays on the primary. Its primary sort may be nullable
(NULLS LAST), while its tiebreak column must be unique and non-null. The built-in
detail drill requires explicit environment and tenant context and exactly one usable
primary-key column; it reports no-PK and composite-PK sources as unavailable rather
than silently using unstable pagination.
Schema changes and data mutations do not use that route. They use structured operation endpoints, durable worker jobs, or the exact-service mesh transaction effect lane, where caller authority is evaluated independently of the generic query surface. Ordinary atomic effect batches have an aggregate server budget of at most 24 seconds inside a shared 30-second transport deadline, leaving deterministic room to return the COMMIT outcome instead of racing a client abort. Before its synchronous COMMIT fence, requester disconnect participates in exact-target cancellation and bounded rollback cleanup; after the fence, COMMIT is allowed to settle and its outcome is reported rather than cancelled late. Concurrent index DDL is a separate single-statement, non-transactional protocol with its own long-running guard. Representative large-tenant batches remain a rollout-validation requirement.
Internal service certificates are handled the same way: they authenticate the calling component, but only explicitly inventoried readers may use the generic query surface. Delegated Edge and AI requests remain user requests, and the destination re-verifies the user session.
This boundary does not by itself imply permission to every analytical object. Deployments should describe table, column, and Data Domain entitlement as a separate resource-authorization control.
Step-by-step
Section titled “Step-by-step”- Authenticate through the supported flow.
- Resolve the environment and tenant.
- Use the documented route family for the operation.
- Check success and error fields before using response data.
- For background work, store the job id and monitor job status.
- Surface errors to the operator rather than retrying blindly.
- For v1 query previews, treat EOF without a valid terminal record as an incomplete result and discard its provisional rows.
Common mistakes
Section titled “Common mistakes”Do not call private service addresses directly from browser code or customer automation.
Do not assume that a request with no tenant context will target the tenant you intended.
Do not send DDL or DML through an analytical read route, and do not retry a rejected consistency value with an invented default.
Do not parse the v1 body as newline-delimited JSON. Newlines may appear inside valid JSON values; the four-byte length prefix is the only record boundary.