The Octri Blog
News, guides & deep-dives
Product updates and practical writing on API documentation, SDKs, and developer experience.
Guides4 min read
How to Choose an OpenAPI SDK Generator: 10 Questions to Ask
Ten practical questions for evaluating generated SDKs: spec support, code quality, auth, errors, publishing, monitoring, and exit cost.
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.
Guides5 min read
Documenting webhooks in OpenAPI 3.1, and the half it cannot describe
3.1 finally gave webhooks a home in the spec. It describes the payload, which is the easy part, and says nothing about delivery, which is where integrations break.
Guides5 min read
API-first in practice: what changes when the spec is the source of truth
The phrase is used to mean four different things. Only one of them changes how your team works, and it is the one that makes the spec a build input rather than a report.
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.
Guides6 min read
Getting your API docs cited when someone asks an AI about your product
People are asking assistants what your API does before they visit your site. What gets quoted back is decided by how your docs are structured, not by a file at your root.
Guides5 min read
Publishing SDKs to npm, PyPI, Maven Central and the rest
Seven registries, seven sets of rules, and two languages that have no registry at all. The decisions you cannot take back are all made before the first release.
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.
Guides5 min read
Your MCP server needs documentation, and it is not your API docs
There is no spec format for MCP servers yet, so what an integrator gets is a README and a config snippet. Here is what actually has to be in it.
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.
Product3 min read
The Octri CLI: Your Whole Project From a Terminal
One binary pushes your spec, builds SDKs in ten languages, publishes docs, uploads source maps from CI, and reads back the production errors those SDKs report. It carries an MCP server, so an AI assistant can drive the same commands.
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.
Guides5 min read
Your changelog is part of your API
Every integrator eventually asks the same question: did something change? If the answer lives in a release-notes page nobody subscribes to, they ask your support queue instead.