Governing Multiple APIs with a Single OpenAPI Style Guide
Quick answer: A style guide is only useful when it is executable and shared. Encode naming, versioning, and error conventions as rules that a CI check runs against every API,
Read articleThe Powerduck Blog
API engineering, from the spec out
Product updates, engineering notes, and guides for designing, debugging, testing, mocking, and serving MCP tools from one OpenAPI spec.
Browse the guidesMulti-Language API Docs: Translating Content Without Forking the Spec
Quick answer: The OpenAPI contract is language-neutral; the prose around it is not. Translate the human-facing descriptions, not the structural schema, and keep every locale pulling from the same source
Read articleHandling Cookies and Sessions: A Client's Cookie Jar vs a Spec-Aware Flow
Quick answer: A client's cookie jar is convenient but implicit: it stores and resends session cookies automatically, which makes an authenticated flow look effortless while hiding the actual
Read articleOffline API Debugging When the Client Requires a Cloud Login
Quick answer: If your API client refuses to work without signing into a cloud account, you have handed a core part of your workflow to a network round trip you
Read articleScanning MCP Tools for Security Issues Before Your Team Deploys Them
Quick answer: An MCP tool is a piece of code that can read and act on real data, so it deserves the same security review as any service you deploy.
Read articleWhen Cursor's Agent Ignores the MCP Tool and Writes a Raw fetch
Quick answer: If your agent has a working MCP tool for an API but the model still hand-writes a fetch, the failure is usually one of three things: the tool&
Read articleManaging API Environments with Plain Files Instead of Cloud Workspaces
Quick answer: An API environment is just a named set of variables: base URLs, credentials, and feature flags. Keeping those in plain, version-controlled files instead of cloud workspaces gives you
Read articleDefining Webhooks and Callbacks in OpenAPI: Outbound Requests as Part of the Contract
Quick answer: Webhooks and callbacks are HTTP requests your service makes, not ones it receives, and they deserve the same contract discipline as inbound operations. Define their payloads, signing, and
Read articleCodegen and readOnly/writeOnly: Why Create Models Include Server Fields
Quick answer: The readOnly and writeOnly keywords exist precisely so a generator can split one schema into the shape a client receives and the shape it sends. If your generated
Read articleWhen an MCP Tool Errors: Structured Tool Errors vs a Raw Exception
Quick answer: An MCP tool should return a structured, machine-readable error when something goes wrong, not let a raw exception bubble up. The agent calling the tool has to decide
Read articleTests That Use Random Data Without a Seed: Why They Fail on Tuesday
Quick answer: Randomized test data is a good idea; an unseeded random generator is not. Without a fixed seed, every run explores a different input, and when a failure occurs
Read articleMocking SSE: Streaming Events and How a Client Handles a Dropped Connection
Quick answer: Mocking a Server-Sent Events endpoint is not the same as returning a list. The value under test is the stream over time: the framing of each event, the
Read article