Information
- OpenAPI version:
3.1.1
Overview
Alvo v1
Section titled “Alvo v1”The Data API Alvo generated for the vehicle-registry example descriptor. Every descriptor generates its own document at GET /openapi/v1.json (with a UI at /scalar); see Data API conventions.
The Data API of one Alvo backend, generated from the project descriptor this host booted with. Changing the descriptor changes this document; none of it is hand-written.
Every route here is generated from the applied Alvo descriptor: an entity declared in the descriptor is the explicit decision to expose it, and a field marked hidden is the per-field opt-out. It appears in no response schema, and in a request schema only when the descriptor also marks it required — a mandatory field a caller cannot see could not be supplied at all, so the name is published only where a caller must read it to perform the write.
Default-deny. Nothing is reachable without a policy that admits the caller for that entity and operation. An operation the descriptor configures no rule for is refused for everybody.
Refusals are RFC 9457 problem documents (application/problem+json) whose type classifies the refusal under https://alvo.dev/errors/. Branch on type; detail is prose and, per RFC 9457 §3.1.1, ought not be parsed. A refusal carries every reason at once in violations, each with a JSON Pointer, a stable code and a fix suggestion.
Every response is Cache-Control: no-store, refusals included. These representations are policy-masked per caller, and the ETag is minted over the row’s version rather than over the response bytes — which is the only tag If-Match’s strong comparison could ever match, and the reason no intermediary may keep the body.
A 500 is not documented on any operation, and its body depends on the host. An invariant the implementation itself relies on propagates past Alvo’s endpoints untouched, so what a 500 looks like is the host’s decision and not a promise this document can make. A host that opted in (AddAlvoProblemDetails()) answers with the same problem document as every other refusal, under https://alvo.dev/errors/internal — which is why that value is in type’s list. A host that did not composes its own.
A request the web server would not read is not documented on any operation either. A body over the server’s limit, one that arrived too slowly, or one whose framing broke never reaches the operation, so no operation can promise a status for it. A host that opted in answers it under https://alvo.dev/errors/unreadable-request, at the status the server chose (413, 408 or 400) — the second value in type’s list that no operation lists.
Authentication
Section titled “Authentication”alvoApiKey
Section titled “alvoApiKey”An Alvo API key, presented as <keyId>.<secret>. A key that cannot be used — unknown, revoked, expired, malformed, or issued for another tenant — is a 401 with one wording for all of them. The header’s name is host configuration; this is the name this host reads.
Security scheme type: apiKey
Header parameter name: X-Alvo-Api-Key