The Octri Blog
News, guides & deep-dives
Product updates and practical writing on API documentation, SDKs, and developer experience.
Engineering16 min read
What Leaves Your Process: The Life of a Monitoring Event
Every error your generated SDK reports crosses a line: out of your process, over the wire, into our disk. Here is what is inside it, the two scrubbers it passes on the way, where it sleeps, when it dies, and how you make us forget someone.
Engineering5 min read
What counts as a breaking change when your SDK is generated
A one-line spec edit can break every call site your users wrote. Here is the table of what is additive, what is breaking, and which ones your spec diff will not warn you about.
Engineering5 min read
Your operationIds are your public method names, and unique is not enough
An operationId is not documentation metadata. It is the name your users type. Here is why uniqueness does not save you, and what actually collides.
Engineering5 min read
Should you hand-write your SDKs or generate them?
The honest answer depends on how many languages you ship and how often your API changes. For one language and a stable API, hand-writing wins.
Engineering5 min read
41% of APIs drift within 30 days, and most of it is invisible
Schema drift is not usually a breaking change. It is a field nobody told you about, found by a test that failed in CI two weeks later.
Engineering5 min read
How many tools should an MCP server expose?
Exposing your whole API to an agent makes it worse, not more capable. Tool choice is a selection problem, and every extra option makes the selection harder.
Engineering5 min read
MCP vs OpenAPI: they answer different questions
The comparison is framed as a replacement and it is not one. One describes an API to people and compilers. The other hands a running agent a set of things it may do.
Engineering6 min read
Giving an agent write access to your API: what to exclude first
A tool call is a real request against a real API. Before you connect one, the question is not which endpoints to expose. It is which ones an agent must never reach.
Engineering5 min read
Modelling API errors in OpenAPI so your SDK can throw something useful
Most specs describe the happy path in detail and the failures not at all. That asymmetry lands on every consumer as one untyped catch block.
Engineering5 min read
llms.txt for API docs, and what AI crawlers actually read
A file at your docs root that tells a model what your product is and where to look. Cheap to publish, easy to get wrong, and not a substitute for the thing it points at.
Engineering5 min read
What your OpenAPI security scheme actually produces in an SDK
A security scheme is not documentation. It is the auth configuration your generated client ships with, and a spec that declares none produces a client with no way to authenticate.
Engineering6 min read
Retries, timeouts and idempotency: the parts of an SDK nobody hand-writes
Every client library needs them and almost no hand-written one has all three. The defaults matter more than the knobs, because most consumers never touch the knobs.
Engineering5 min read
Why coding agents invent endpoints you never shipped
An agent asked to integrate your API will recite one it saw in training or guess from the name. Both produce code that looks right and does not run. The fix is not a better prompt.
Engineering5 min read
Four ways APIs paginate, and what each one does to your SDK
Cursor, offset, page number, next URL. Your choice decides whether your users write a loop or you write it for them, and whether the loop is even correct.
Engineering4 min read
Why generated SDKs break silently, and how to make them observable
Generated SDKs go dark the moment they ship. Here's why they fail silently in production, and the three pieces you need to de-minify their stack traces and see the failures.
Engineering2 min read
Ten Habits for Writing Great OpenAPI Specs
Small, consistent choices in your OpenAPI document produce dramatically better generated docs and SDKs. Here are ten that pay off.