APIs
A captured API entry vendors one OpenAPI document and names exactly the operations the realm may call.
apis: { statuspage: { url: "statuspage.json", // a file under apis/, vendored name: "statuspage", // the gateway namespace type: "openapi", auth: "api-key", credential: "statuspage-key", headers: { "X-Client": "realm-oncall-radar" }, operationIds: ["listUnresolvedIncidents", "listIncidents"], writeOperationIds: ["acknowledgeIncident"], },},The typed gateway has one method per listed operation under ctx.gateway.<name>. A read takes
an untyped arguments object: ctx.gateway.statuspage.listIncidents({ services }). A write takes
an arguments interface built from the vendored document, holding its path and query parameters
and its request body under the reserved body argument, and a field the operation does not
declare is a compile error:
await ctx.gateway.statuspage.acknowledgeIncident({ incidentId: input.incidentId, body: { note: "Seen by the on-call radar" },});A write is checked against the admitted request schema. An operation may not declare a
parameter named body, which is reserved for its request body. The current portable response
is a parsed JSON body with no envelope; narrow it before use. Additional codecs, raw responses,
media parameters and streaming return types are not yet specified. SDK support for those
forms is not evidence that a host supports them. The separately marked NDJSON proposal in
the hosted contract does not change this current profile.
The host checks at installation:
- At most 32 entries and 128 operations across them. The entry’s key is a JavaScript identifier.
nameis[A-Za-z_][A-Za-z0-9_-]{0,63}and unique. Two operations may share an id in different namespaces, and are refused when their qualified names collide (<name>.<id>,<name>_<id>, or the two camel-cased and joined with_). urlis a bare filename,[A-Za-z0-9_-]+\.json, underapis/, at most 1 MiB, OpenAPI 3.x, with every$refpointing under#/components/, at most 256 paths, and each operation id declared once. YAML OpenAPI documents are not in this captured profile; SDK acceptance does not extend it. Legacyapis/apis.ymlremains limited to 64 KiB.- For authenticated APIs, exactly one of
credentialortokenEnv, and acredentialmust be declared incredentials.tokenEnvis deprecated in favour of a declared credential: it matches[A-Za-z_][A-Za-z0-9_]{0,127}, may not start with__embabel_sql_v1__, and becomes an implicit credential, with a warning. The implicit credential’s id is the variable name spelled as written, which the declared-id pattern does not cover; the host reads a credential id in either spelling (see credentials and databases). Two entries reading onetokenEnvmust declare the sameauth. Anauth: "path"entry cannot usetokenEnv. operationIdslists 1 to 128 reads, each aGETwith no request body.writeOperationIdslists up to 64 writes, each aPOST,PUT,PATCHorDELETE. An operation is in one list, never both, and every listed id must exist in the document.- The document has exactly one
httpsserver on port 443, with no user info, query, fragment, server variables, percent-encoded path,.or..segment or{placeholder (other than{credential}underauth: "path"), and no per-path or per-operation server override. - An operation path matches
^/[A-Za-z0-9_~./{}-]*$with no.or..segment. Parameters are declared inline, inqueryorpath, with astring,integer,numberorbooleanschema: at most 64 per operation, named[A-Za-z_][A-Za-z0-9_-]{0,63}, none repeated across the path item and the operation. A path parameter isrequired, and the path’s placeholders and its path parameters match exactly. Anenumholds at most 128 non-null scalars, andminLengthandmaxLengthare whole numbers from 0 to 2048. - A request body holds only
content, with one media type,application/json, whoseschemais an object. - For bearer or API-key authentication, security is exactly one requirement naming one scheme, with no scopes. For
bearerit is anhttpscheme whose word matches the credential’sscheme. Forapi-keyit is anapiKeyscheme in a header or the query, named[A-Za-z][A-Za-z0-9-]{0,127}, and the header may not be one the host owns (Authorization,Cookie,Host,Content-Typeand the like). The field the credential travels in may not also be a fixed header or a parameter. auth: "path"puts the credential in the URL and needscredential. The document writes{credential}in the server URL or in the path of a declared operation, so that each declared operation’s full URL carries it exactly once, in the path, never in a query string.securityis absent or empty, and no operation takes acredentialparameter. The typed client takes no argument for it.auth: "none"is a public read API: no credential ortokenEnv, absent or empty security, GET operations only, and no write grants. Keyless access still needs operation approval.- Up to 16 fixed headers, each named
X-...and holding at most 1,024 printable ASCII characters, with no${substitution. Two header names that differ only in case are refused. Authors cannot overrideUser-Agent; the host owns it except when the admitted authentication scheme uses that header for its key.
Each operation is approved by the owner on its own, reads and writes under separate grants; see captured API operations for what the host does on every call.

