From an OpenAPI spec to a typed workflow node at runtime, with no codegen and no backend

Every automation tool hits the same wall: it has integrations for the top N apps, and then your API isn’t on the list. You can wait for someone to build a connector, or write a backend to glue it in.

In AWFlow (a workflow builder that runs in a browser extension), the answer is a Custom API node: paste the URL of an OpenAPI spec, pick an operation, and the node renders that operation’s fields and calls it. No codegen step, no server. This post walks through how it works, and what I deliberately left out.

From a spec URL to a request

The whole node is a short pipeline. Each arrow is a small, pure function, which makes the whole thing easy to test.

Inside each step

1. Fetch (and cache) the spec

const res = await fetch(specUrl, { headers: { Accept: 'application/json' } });
const text = await res.text();
try { return JSON.parse(text); }
catch { throw new Error('The OpenAPI spec could not be read as JSON. Only JSON specs are supported for now.'); }

Parsed specs are cached by URL in a Map<string, Promise<Spec>>. The operation dropdown and the dynamic form both need the spec, and without the cache every keystroke in the form re-fetched it. Failures are evicted from the cache so a retry actually retries.

YAML is rejected on purpose, with a clear message.

2. Normalize the spec into a flat operation list

The node needs a small slice of the spec:

interface OApiOperation {
  operationId: string;   // from the spec, or synthesized: `get_/pets/{id}` → "get_pets_id"
  method: string;        // GET, POST…
  path: string;          // /pets/{petId}
  parameters: { name: string; in: 'path' | 'query' | 'header'; required: boolean; schema: JsonSchema }[];
  requestBody?: { required: boolean; schema: JsonSchema };  // application/json only
  security?: Record<string, string[]>[];
}

Some details came from real specs rather than the spec document:

3. Turn an operation into a form

This is the part that makes it feel native. Each operation becomes one JSON Schema object: one property per parameter, plus a body property for a JSON request body, with required carried over:

function buildOperationSchema(op: OApiOperation): JsonSchema {
  const properties = {}, required = [];
  for (const p of op.parameters) {
    properties[p.name] = { ...p.schema, ...(p.description ? { description: p.description } : {}) };
    if (p.required) required.push(p.name);
  }
  if (op.requestBody) {
    properties.body = op.requestBody.schema;
    if (op.requestBody.required) required.push('body');
  }
  return { type: 'object', properties, ...(required.length ? { required } : {}) };
}

The node system already renders forms from Zod schemas, so the JSON Schema is converted to Zod at runtime and handed to the same form renderer every other node uses. Enums become dropdowns, required fields are marked, descriptions become tooltips. Here is what that looks like on the canvas, with the public Petstore spec:

4. Build the request and apply auth

for (const p of op.parameters) {
  const v = values[p.name];
  if (v == null || v === '') continue;
  if (p.in === 'path')   path = path.replace(`{${p.name}}`, encodeURIComponent(scalar(v)));
  if (p.in === 'query')  query.set(p.name, scalar(v));
  if (p.in === 'header') headers[p.name] = scalar(v);
}

Auth follows the operation’s security scheme, using a credential from the extension’s local store. Secrets never come from node parameters, so they’re never stored in the workflow itself or carried along when you share it.

• apiKey → header (default) or query parameter, under the name the spec declares
• http + bearer → Authorization: Bearer …
• http + basic → Authorization: Basic …

The JSON body is serialized with Content-Type: application/json, and the response is parsed by content type (JSON → object, otherwise text, 204 → { success: true }). Errors include the status and the first 500 characters of the body. That’s usually exactly the validation message you need.

Why the extension, and what’s left out

5. Why it has to run in the extension

Arbitrary API hosts don’t send CORS headers for random web origins. So the Custom API node is extension-only: the request is made from the extension, which can reach hosts the user has granted. (The difference between running in a browser and on a server has its own post.)

The spec URL field is a “URL with permission” field: entering it shows a Grant access button for that origin, and the run is gated on that grant. You can see and revoke exactly which hosts a workflow can talk to.

(Known limitation: the API’s servers[] host is assumed to match the spec’s host for that grant. That’s the common case, but not universal.)

What I deliberately didn’t build (yet)

Each of these is real work, and none of them was blocking the common case: “this SaaS has a JSON OpenAPI spec and an API key”. I’d rather ship the 80% with clear errors than a 100% that half-works. When the API has no spec or needs a non-JSON body, the plain HTTP Request node is the fallback; the Custom API node docs list both.

Runtime vs. codegen

Codegen (openapi-generator, orval…) gives you types at build time, which is great when you own the code. In a no-code tool the user brings the spec at runtime, so there’s no build step to generate into.

The trade-off is that type safety moves from the compiler to schema validation in the form. In practice, for “call this endpoint with these five fields”, that’s the right place for it.

AWFlow is free. If you point the Custom API node at a spec and it chokes, send me the spec URL. That’s how this list of limitations gets shorter.