Wrapping an API

An Airnode is configured with the OpenAPI description of the API it wraps, in version 3.1 or 3.2. Providers already have one, tooling already understands it, and there is nothing Airnode-specific to learn.

The one assumption is that the API is HTTP based. Requests go to the document's servers[0].url, and every GET and POST operation in the document becomes an operation the Airnode serves, keyed by its operationId. $ref is resolved, so a document that leans on components works as-is.

Operations and their inputs

An operation's inputs are its parameters and, for a JSON requestBody, that body's properties. Both arrive as one flat set of named values. A query, header or path parameter is a string, since it has to survive being written into a URL, and a body property keeps whatever type it was declared with.

Only the outermost type of a value is checked. An array has to be an array, which catches a caller who sent the wrong kind of thing, but what is inside one is the upstream's own schema to enforce. Checking deeper would mean maintaining a second copy of an API the Airnode does not own.

Narrowing by declaring less

An Airnode does not have to serve all of an API. It narrows by declaring less of it: anything the document does not mention is refused before the upstream is called. So the document is both what the Airnode forwards to and the limit of what it will forward, and there is nothing to write to exclude the rest.

Keys the upstream wants

Most APIs worth wrapping want a key, and the document already has a way to say so: components.securitySchemes names the credential and security says it applies. Bearer tokens and API keys in a header or the query string are understood. What the document never holds is the value.

Each scheme becomes an environment variable instead, so the document stays committable and the credential stays with whoever deployed it. That is the same line the signing mnemonic already sits on. The document is the integration and decides which API is wrapped. The environment is the deployment and decides who is running it. Neither has to know the other to be written, and a deployment that forgot a key is refused at boot rather than failing every call.

The credential is attached to the upstream request after everything the caller sent, so a caller cannot shadow it. It is not a parameter, which means it is absent from the request hash and from the document the Airnode publishes.

This is also where a private upstream URL stops being a convention and starts being enforcement. An Airnode over a public endpoint keeps its URL to itself, but a determined caller could find it. An Airnode holding a key is one a caller cannot go around, because the key is the thing they do not have.