I maintain a small public API and my release notes used to be whatever I remembered an hour after deploying. So I wrote a deterministic OpenAPI differ: feed it a base spec and the new spec, get back a structured list of changes, no LLM in the loop to embellish anything. The first real run compared…
Every API team has a postmortem that starts with "we didn't think that was a breaking change." A field that was always present becomes optional; an enum gains a value clients treat as exhaustive; a response code changes from 200 to 201; a query parameter that used to be ignored is now required.…
A TypeScript codebase that talks to an HTTP API should not hand-write request and response interfaces. It will not keep them in sync for a month. The question is which generator to use, and the answer depends on how much runtime you want generated alongside the types. The ecosystem splits into…
Webhooks are the most under-documented part of an API surface and the part most likely to page someone at 3 a.m. Consumers cannot discover them by making requests — the server calls them — so the document is the only thing standing between an integration and guesswork. OpenAPI 3.1 fixed the…
Every OpenAPI document starts as one clean file. Then it reaches forty operations and the file is 2,000 lines, then a hundred operations and pull requests conflict on every merge, then nobody edits it without a full afternoon of context. The standard advice is "split it with $ref ," which is true…
If you maintained OpenAPI documents between 2018 and 2023, Stoplight Studio was probably on your machine: a desktop editor that combined a form-based operation view with raw YAML, no account required, and it understood $ref across files. Studio's active development ended as Stoplight shifted to its…
A mock server is only as good as the spec behind it, which is why most mock-server comparisons are useless — they use a petstore document with three routes and no auth. We took a real 40-operation OpenAPI 3.2 spec: cursor pagination, bearer auth, multipart upload, one SSE stream, four error…
Days 2 through 4 covered the easy case: a new API where the spec can come first. Most of us live in the other case. The service is three years old, the original team is gone, the docs are a Postman collection from 2023, and two hundred routes keep production running. Day 5 of the the series is…
