How-to › Ship an SDK

How to generate a client from a vendor spec you cannot edit#

Repair a vendor's OpenAPI document with an Overlay before any generator reads it, then check the generated client against responses recorded from the live API.

Audience
API consumer
Level
intermediate
Topic
Choose a generator and generate an SDK
Languages
TypeScript and Python
Verified

Open-Meteo’s OpenAPI document says a forecast is one JSON object. Ask for two places in one request and the API answers an array, so a client generated from that document rejects or mangles the answer. The file lives in the vendor’s repository, and a copy you edit by hand falls behind the moment the vendor commits again.

What you get

You will end up with an Overlay that repairs a copy of the vendor’s document, and a client generated from that copy and tested against recorded live responses. This is for you if you call an API whose document somebody else writes.

Short answer

Record a few real responses from the vendor’s API and validate them against its OpenAPI document. Write each mismatch as an action in an OpenAPI Overlay, apply it to a copy with openapi-format before any generator runs, and generate from the copy with Hey API or Kiota. Then run the generated client against a stand-in that replays the recorded responses. The vendor’s file stays untouched, so its next release is a download and a rerun.

You will need

Node 22 or later, the vendor’s document pinned to a commit, and network access once, to record responses. The vendor here is Open-Meteo, whose forecast document is an OpenAPI 3.1 file in its server repository.1 The sample does not copy that file. Its forecast.yml is a short document of its own with the same three defects in the same places, and record.sh reads the vendor’s file at the pinned commit to prove it. OpenAPI 3.1 schemas are JSON Schema 2020-12, so the checks use Ajv in that mode.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hand-written callsOne endpoint and a few parameters, as with this forecast callA person reads the vendor’s changelog and finds every schema change by handYou call more than a handful of operations
Hey API parser.patchYou generate TypeScript and want the repair inside the generator’s configThe repair is code in one tool’s config, which a second generator cannot reuseTwo generators read the same document
Kiota include-path filteringA large document where you call a few pathsIt drops paths and operations only, so a broken schema on one you keep still arrivesThe defect sits inside an operation you need
OpenAPI Overlay applied before generationAny generator, and repairs you want reviewed as a data fileOne more build step, and actions that match nothing pass unless you checkThe vendor will merge a fix upstream before you ship
openmeteo, the official vendor SDKYou want the vendor to own the client, retries includedFlatBuffers instead of the documented JSON, and retry rules you read in its sourceYou need the JSON the document describes, or your own retry policy
voxgig-sdk catalog SDKA Go program, and a client that somebody else generated for youBuilt from the catalog’s own document, and on the Go module proxy but not npm or PyPIYou need TypeScript or Python from npm or PyPI

Voxgig maintains the SDK Catalog, the last row. None of the other five rows is Voxgig’s.

The Overlay and Hey API’s patch make the same repair in two places. The Overlay is a YAML file that any generator’s input can pass through, and it costs one build step. The patch needs no extra tool but binds the repair to Hey API. Kiota’s filter answers a different problem: it shrinks a document and repairs nothing inside what it keeps.

Record what the API sends

record.sh saves three real responses, one place, two places, and one place with timeformat=unixtime, and refuses a status other than 200 or a body that is not JSON. It writes the day it ran into records/recorded.txt.

live() { # name, query
  local code
  code=$(curl -sS --retry 6 --retry-delay 5 --retry-all-errors -o "records/$1" -w '%{http_code}' "https://api.open-meteo.com/v1/forecast?$2")
  [ "$code" = 200 ] || { say "$1 answered $code"; exit 1; }
  node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "records/$1"
}

validate.mjs checks each record against the 200 schema of three documents: forecast.yml, its repaired copy, and the one the catalog’s Open-Meteo SDK was generated from. It also lists keys on the wire that a schema never names.

node validate.mjs
record         document repaired catalog
single.json    pass     pass     pass
multi.json     FAIL     FAIL     FAIL
unixtime.json  pass     FAIL     FAIL
why
  document on single.json: $.current_units.interval is on the wire, not in the document
  document on multi.json: $ must be object
  repaired on multi.json: $ must be object
  catalog on multi.json: $ must be object
  repaired on unixtime.json: /hourly/time/0 must be string
  catalog on unixtime.json: /hourly/time/0 must be string

Every document rejects the two-place answer. forecast.yml also omits current_units.interval, and the catalog’s document types every time as a string, so it rejects Unix times. The repaired copy rejects them on purpose, as the next section explains. Run on the vendor’s file, record.sh printed the same table into records/vendor-validate.txt, and the test compares the two line by line.

Write the repairs as an overlay

An Overlay is a list of actions, each a JSONPath target with an update or a remove. Version 1.1.0 of the specification is the edition this file declares.2

actions:
  - target: $
    description: Kiota and Hey API found no base URL in the servers on the path item.
    update:
      servers:
        - url: https://api.open-meteo.com
  - target: $.paths['/v1/forecast'].get.responses['200'].content['application/json'].schema.properties.current_units.properties
    description: The wire carries current_units.interval and the document omits it.
    update:
      interval:
        type: string
  - target: $.paths['/v1/forecast'].get.responses['200']..[?(@.type[0] == 'string' && @.type[1] == 'integer')].type[1]
    description: This client sends timeformat=iso8601 only, so every time value is a string.
    remove: true

The vendor puts its servers on the Path Item, which OpenAPI allows. On that file Kiota printed No server url found in the OpenAPI document, and Hey API wrote its client with no base URL, so the first action copies the URL to the root. The third action narrows [string, integer] to a string. The client Kiota generated from the vendor’s file threw on the one-place answer, but the one from the repaired copy read it.

repair.mjs applies the file with openapi-format to a clone and lists every leaf that moved.

node repair.mjs
overlay 3 actions, all matched; the input file is unchanged
  removed <200 schema>.properties.current.properties.time.type[1]
  added   <200 schema>.properties.current_units.properties.interval
  removed <200 schema>.properties.daily.properties.sunrise.items.type[1]
  removed <200 schema>.properties.daily.properties.sunset.items.type[1]
  removed <200 schema>.properties.daily.properties.time.items.type[1]
  removed <200 schema>.properties.hourly.properties.time.items.type[1]
  removed <200 schema>.properties.minutely_15.properties.time.items.type[1]
  added   $.servers
repaired copy is the one generate.sh fed Hey API: true

records/vendor-repair.txt lists the same eight changes for the vendor’s file.

Generate from the repaired copy and call it

generate.sh writes the repaired copy to a scratch file and points Hey API at it, with its Zod plugin checking every response.

export default {
  input: process.env.REPAIRED_DOC,
  output: { path: process.env.HEY_OUT, importFileExtension: '.js' },
  plugins: ['@hey-api/client-fetch', 'zod', { name: '@hey-api/sdk', validator: true }],
}

forecast.mjs wraps the generated function in a few lines you own. It takes one place as two numbers, always sends timeformat=iso8601, and throws when the validator rejects a response.

node call.mjs
one place through the wrapper
  timezone GMT, current keys interval is_day temperature_2m time weather_code
  current_units.interval "seconds"
two places through the wrapper
  TypeError: latitude must be one finite number
two places through the generated function directly
  status 200, data undefined, validator: Invalid input: expected object, received array
stand-in saw 2 requests: GET /v1/forecast, GET /v1/forecast

The wrapper refuses a comma-separated latitude before any request leaves. Called directly, the generated function gets a 200 and returns no data, with the Zod error in its error field.

Check it worked

client.test.mjs holds the page’s claims to the committed records, and holds the stand-in to the error answers record.sh saw live.

node --test client.test.mjs
1..16
# tests 16
# suites 0
# pass 16
# fail 0
# cancelled 0
# skipped 0
# todo 0

Repair the same document in Kiota and Hey API

Kiota’s generate --help names no overlay option, and neither does its usage page, so a Kiota build applies the Overlay first and passes the copy as -d. record.sh ran Kiota once, on the vendor’s file and on its repaired copy, and called both clients against the stand-in. It set KIOTA_CLI_TELEMETRY_OPTOUT=true, the variable the usage page gives for telemetry. The clients are not committed.

tail -n 6 records/kiota.txt
== runtime 1.0.0-preview.113, serialization-json 1.0.0-preview.114
vendor doc, one place: threw encountered an unsupported type during deserialization string
vendor doc, two places: returned keys [additionalData], additionalData keys [0,1], latitude undefined
repaired doc, one place: returned keys [current,currentUnits,daily,dailyUnits,elevation,generationtimeMs,hourly,hourlyUnits,latitude,longitude,timezone,timezoneAbbreviation,utcOffsetSeconds], additionalData keys [], latitude 52.512604
repaired doc, two places: returned keys [additionalData], additionalData keys [0,1], latitude undefined
stand-in saw 4 requests

In that runtime, the message comes only from the reader for a list of primitives, which throws when an element is not the type it was asked for. The repaired copy reads one place. Two places come back as an object holding 0 and 1, with no error, so a Kiota caller needs the same one-place wrapper. --include-path '/v1/forecast#GET' changed only kiota-lock.json, because the vendor’s file has one path.

Hey API can carry the repair in its own config. Its parser page documents patch.schemas; the 0.99.0 package also takes an input function and operations keys, in patchOpenApiSpec. record/hey-patch.config.mjs uses input to add the root server and an anyOf of one forecast or an array of them, with parser.filters as the trim. For the vendor’s file and for forecast.yml, records/hey-patch.txt reads two places: an array of 2, validator error: no.

When it goes wrong

An action matches nothing after the vendor renames a path. openapi-format lists it under unusedActions, applies the others, and raises no error, so repair.mjs stops with overlay actions that matched nothing.

A request answers 200 but the data is undefined. Hey API returns a validator failure in error rather than throwing, unless throwOnError is set. Check error on every call, as forecast.mjs does.

Production fails on an answer the tests never saw. The records are a snapshot, so the vendor can change the wire without changing the document. Rerun record.sh when you move the pinned commit, and read the diff of records/. It checks the vendor file’s hash first, so a moved commit is an edit to the script.

When not to do this

Do not generate a client for one endpoint with a dozen parameters. The wrapper here is most of the code you would write by hand, and the generated directory is more to review than the call.

Do not take the vendor’s SDK without reading it. openmeteo asks for format=flatbuffers, a parameter the JSON document does not declare, so the document says nothing about what it parses. official.mjs shows it sends three requests on a 502 and one on a 503.3

Do not adopt the SDK Catalog’s Open-Meteo client as a TypeScript or Python package. records/registries.txt shows npm and PyPI answering 404, and its document rejects Unix times.

Pick Kiota over Hey API when you need C#, Go, Java or PHP from the same repaired copy, all on its list of languages. Pick Hey API when the API answers a union, since its patch produced a working array response here.

Last verified

Verified 2026-11-22 against Node 22.23.5, openapi-format 1.34.0, Ajv 8.20.0, Hey API 0.99.0, TypeScript 5.9.3 and openmeteo 1.2.3. Kiota 1.39.0 and its TypeScript runtime ran once, on the vendor’s file, in the Kiota step of record.sh. That step did not run again when the other steps were recorded, and every sentence about Kiota rests on records/kiota.txt. The catalog’s Go SDK was not run; this page checks only its document and where it is published.

Footnotes

  1. The repository keeps nine such documents under openapi/, one per API, beside the Swift server that answers them. The forecast document’s info.license names CC BY 4.0, which the README gives as the license of the weather data, while the source code is under the GNU AGPL, version 3 or later. OpenAPI defines that field as the license of the exposed API, so it does not say which of the two covers the file. ↩︎ Back to text

  2. The revision history dates 1.0.0 to 2024-10-17 and 1.1.0 to 2026-01-14. The copy action arrived with 1.1.0; the 1.0.0 text has update and remove only. This overlay uses no copy, and a test applies it under overlay: 1.0.0 to the same result. ↩︎ Back to text

  3. The retry list in the SDK’s source is 500, 502 and 504. A 503 falls through to the FlatBuffers decoder, which in the demo returned one response built from a JSON error body. The helper that sleeps between attempts declares a default backoff factor of 0.5, which the one exported function never uses, because it passes 0.2. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.