Topic
Most OpenAPI upload specs are subtly wrong: the file is typed as a string, the multipart boundary is undocumented, or an array of files generates the wrong client. Here is how to model each of the three real upload shapes so codegen, mocks, and scanners all agree.
Read articleVersioning is less about where the number goes than about knowing what actually breaks a client and communicating the sunset. Here is the honest tradeoff between path and header versioning, a breaking-change checklist, and how to enforce it with OpenAPI diffs in CI.
Read articleInline every schema and your request and response models drift apart. Extract everything and the document becomes a maze of one-off references. The middle path is a small set of rules for what becomes a component, what stays inline, and how to name and compose it.
Read articleMost teams expose everything as MCP tools and end up with a catalog the model cannot navigate. The protocol defines three primitives for a reason: tools act, resources are readable context, and prompts package reusable workflows. Here is how to decide, with examples from an API platform.
Read articleHuman callers read prose and ask a teammate when confused; agents retry, chain calls, and act on whatever a response most resembles. A few design rules separate APIs agents use reliably from ones they misuse: idempotency, strict schemas, machine errors, and async jobs.
Read articleBehavior first, routes second. AI drafts the OpenAPI contract as reviewable diffs, the team settles money, idempotency, and error envelopes up front, and mocks plus scenarios define done before implementation starts.
Read articleA grounded look at the review gates that keep AI-generated APIs usable: staged plans, granular JSON Patch cards that never overwrite your fields, read-before-edit tools, and deterministic validation.
Read articleA booking app built from one prompt can pass every visual check and still fail on time zones, double bookings, and stale cancel responses. Teams need a contract both people and tools can query, change, and verify.
Read articleEvery API invents an error envelope once; integrations then handle a bespoke format per vendor. RFC 9457 Problem Details is the machine-readable standard, and it extends cleanly to validation and multi-error responses.
Read articleOffset pagination is easy until data changes under the client; cursors are stable but opaque and bad for jump-to-page. Here is how to choose, how to document each style in OpenAPI 3.2, and the response envelope that stops frontend teams guessing.
Read article