The Octri Blog
News, guides & deep-dives
Product updates and practical writing on API documentation, SDKs, and developer experience.
Showing articles tagged #openapi.
Engineering2 min read
Your streaming API returned 200. Then it failed
An HTTP success status starts a stream; it does not prove the operation finished. Design explicit completion, interruption and recovery semantics.
Engineering3 min read
OpenAPI describes endpoints. Arazzo describes how to use them together
Describe dependencies, inputs and success conditions across API calls. Use Arazzo to make integration workflows explicit alongside OpenAPI.
Engineering3 min read
One API spec, three audiences: stop maintaining three copies
Derive public, partner and internal API descriptions from one base contract. Use repeatable overlays and validate each audience's output.
Engineering3 min read
Your OpenAPI spec can generate bug reports, too
Use schema-driven and stateful tests to explore API behavior. Preserve minimized failures and add business invariants the schema cannot express.
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.
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.
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
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.
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
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.
Guides5 min read
The API docs your OpenAPI spec cannot generate
A generated reference answers what an endpoint accepts. It never answers which endpoint to call, in what order, or what to do when one fails. That part is yours.
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.
Product3 min read
Inside Octri API Studio: Docs You Edit Like an App, Not a Repo
API Studio is a three-pane visual workspace for your docs. Edit an endpoint, watch the page render beside it, drag pages into groups, tune the playground and SEO, and publish a version. No markdown-in-a-repo ceremony.
Product3 min read
Inside Octri SDK Studio: Tune Every SDK, See the Code Change Live
SDK Studio turns every knob on your generated SDKs in a real UI, per endpoint, with a live preview of the code as you change it. Package names, retries, pagination, streaming, deprecations, auth, custom transforms, and which endpoints ship.
Comparisons4 min read
Octri vs. Fern: Docs & SDK Generation Compared (2026)
Fern and Octri both turn one API definition into docs and SDKs. Octri adds production monitoring Fern has no answer for, more languages including Rust, a nicer docs editor, and a free tier.