SDKs, Alexa and Home Assistant

clients for one API

4

SDK downloads a month

~3,300

line and branch coverage

100%

tests across the four projects

1,300+

The context

A non-profit platform publishes daily timetables for thousands of community venues. Each venue keeps its own yearly schedule, shown on screens on site, in a mobile app, and more and more on smart speakers and in smart homes. The API existed, but with no documentation and no official library: every client redid the same maths, with the same bugs.

One contract, four clients

It all starts from an OpenAPI 3.1 spec I wrote by hand from the backend’s code. It only describes what clients use, but it describes it exactly. Two in-house generators turn it into a Python SDK and a TypeScript SDK, which in turn power the Home Assistant integration and the Alexa skill.

What was hard

A hand-written contract that doesn’t lie

A hand-written spec drifts at the backend’s first change. Three nets stop that. Custom Spectral rules reject any operation without an id or a description, since those descriptions become the SDKs’ documentation. AJV validates real captured responses with every object closed (additionalProperties: false injected everywhere): an undocumented field fails CI. And every night, a job captures fresh production responses and validates them again.

On the SDK side, the spec is pinned by tag and SHA-256. CI regenerates the code and fails on any difference: you cannot publish a library that doesn’t match the contract.

Generated SDKs that don’t feel generated

I didn’t use openapi-generator: you can tell a generic SDK. My generators (Jinja2 and ruff for Python, templates and Biome for TypeScript) produce the types, resources and client. Transport, errors and timetable maths stay hand-written. And what OpenAPI cannot express becomes a type:

// simplified: OpenAPI cannot say "a position OR words", the generated union can
client.venues.search({ lat: 48.85, lon: 2.35 }) // ok
client.venues.search({ words: 'paris' })        // ok

// @ts-expect-error a latitude needs its longitude
client.venues.search({ lat: 48.85 })

The client retries with backoff and jitter, honours Retry-After up to 60 seconds, cancels cleanly through AbortSignal, and never follows a redirect, so the token can’t leak to another domain.

Time, the real enemy

Each venue publishes wall-clock times, “05:42”, day by day, in its own time zone. Clients need instants. In between: daylight saving changes, events after midnight, relative offsets and invalid entries. Python relies on zoneinfo, TypeScript on Intl alone, with no dependency. An invalid time becomes null rather than a wrong value, and a reference test checks that both SDKs compute the same lunar calendar, month by month, from 1990 to 2060.

A chime on the minute, or not at all

I took over an Alexa skill written by a contractor and re-architected it: JavaScript to strict TypeScript in thirteen PRs, data in DynamoDB, and above all scheduled audio announcements that must play on time, in each venue’s time zone.

A late announcement is worse than a missed one. Past five minutes, the worker drops the message. SQS visibility is cut to 30 seconds so that three attempts fit in the window, and the dead-letter queue raises an alarm but is never replayed. Concurrent writes (voice, website, a widget) only touch their own fields, under a version number, and replay their diff on conflict.

The bar

Home Assistant

The community integration is the one running in people’s homes: I wrote 60 of its 74 merged PRs, with 394 tests, 100% coverage and a UI in six languages. A version for Home Assistant core, co-written, is in review with the maintainers. There, each entity schedules its own next value change instead of polling the API every minute.

What I took away

A good contract is worth more than any generator, and time is the most treacherous domain I know. The rest is tooling, so nobody has to think about it again.