The Octri Blog
News, guides & deep-dives
Product updates and practical writing on API documentation, SDKs, and developer experience.
Showing articles tagged #api-design.
Engineering3 min read
Your API response is eating the agent's context window
Design bounded responses that preserve useful facts. Filter, select and aggregate before large intermediate payloads enter an agent's context.
Engineering3 min read
202 Accepted is the beginning: designing APIs for long-running jobs
Give asynchronous work an operation handle, explicit states and a documented recovery path. Acceptance is different from completion.
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
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.
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.
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
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.