openapi – Türker Yıldırım

The integration that outlived the integrator

Deep diveFebruary 24, 202610 min read

A supplier acquired and shut down, and an endpoint returning 200 with an empty body for eleven weeks.

A type generated from a schema, and the assertion I removed

NoteAugust 15, 20252 min read

Types generated from an OpenAPI document, and a response validated at runtime rather than asserted at compile time. A generated type describes the specification and the specification is…

A package I published, and the API design I got wrong twice

Deep diveMay 19, 202516 min read

turkerdev/php-figma-api, a typed client for a third-party REST API, and two design mistakes that only appear once somebody else uses it.

A URI version, and why it beat a header

NoteApril 3, 20252 min read

Three ways to version an API, and choosing the one that is visible in a log line. The header approach is more correct and the URI approach is…

An API versioned for the first time in six years

Deep diveMarch 6, 202514 min read

Six years of additive-only changes, and a change that cannot be additive. A field whose meaning must change, with four consumers reading it.

The generated specification that drifted from the second version

NoteJanuary 17, 20251 min read

A specification generated from the router, which is drift-proof until there are two routers describing two versions. Generating from the router guarantees that a documented endpoint exists and…

An API that had two clients and three shapes

Deep diveMay 16, 202410 min read

One endpoint, two consumers, and a response that differs by header. Three serialisation paths for one resource, two of them accidental.

A sparse fieldset that was invented by accident

NoteFebruary 7, 20241 min read

A response that omits fields when a header is present, implemented three years ago for one consumer and never documented. The behaviour was correct and the mechanism was…

An error shape agreed once, and used everywhere

NoteNovember 23, 20232 min read

Four error formats across one API, because each was invented by whoever wrote that controller. RFC 7807 is a small specification and the value is not its contents…

An OpenAPI document generated from the router

NoteOctober 2, 20231 min read

A hand-written specification that had been correct in March and described four endpoints that no longer existed. Generating from the router makes drift impossible in one direction —…