The Agent Added a 'Safe' Fallback That Quietly Returned Empty Data
Quick answer: A nullish fallback like data ?? [] is a legitimate way to handle a value that is genuinely optional, but an AI agent often reaches for it to silence a
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 guidesA Stub Matching on JSON Path That Fires on the Wrong Request
Quick answer Over-specific body matching is a quiet source of false positives in a mock. A stub that matches on a JSON path expression, or on a long list of
Read articleMocking a Health Check and Readiness Probe That Fails Until the Stub Is Ready
Quick answer When a mock server runs in a container or a compose stack, it should expose a health and readiness check just like a real service, and the check
Read articlePreviewing Docs for Every Pull Request vs Publishing Only from the Main Branch
Quick answer If docs are generated from a spec, every pull request should produce a preview build that reviewers can open before the change merges. Publishing only from the main
Read articleDocs Feedback Signals vs What Developers Actually Search For
Quick answer A "Was this page helpful?" widget gives you an opinion, but it is a weak and biased signal. The readers who click are a self-selecting minority,
Read articleWhen the Client Follows a Redirect and Re-sends Credentials to the Wrong Host
Quick answer An HTTP client that follows redirects automatically can carry your credentials to a host you never intended to trust. When a 302 or 307 points at a different
Read articleKeeping an Auth Token Fresh Across a Long Test Run vs Re-authenticating Each Request
Quick answer During a long API test run, an access token captured at the start will expire partway through, and a suite that re-authenticates for every single request wastes calls
Read articleVersioning an MCP Server: Changing a Tool's Input Schema Without Breaking Existing Agents
Quick answer Changing an MCP tool's input schema is a breaking change for the agents that already call it, even though there is no compiled client to fail
Read articleWhen Cursor's Agent Reuses a Stale ID from an Earlier Step in the Same Workflow
Quick answer When an agent chains API calls, it is tempted to reuse an identifier it captured earlier in the workflow rather than re-reading the resource. That is fine for
Read articleReviewing API Changes in a Pull Request: Spec Diffs vs Cloud Collection Histories
Quick answer API changes belong in a pull request where the diff is the review artifact. When requests and responses live in a plain spec file, a change to a
Read articleDefining Multiple Security Schemes and When a Client Sends the Wrong One
Quick answer When an API defines more than one security scheme, the client has to choose correctly, and a wrong choice fails in confusing ways. A service that accepts a
Read articleGenerated Clients and Error Responses: Typing 4xx/5xx Bodies Instead of Throwing Blind
Quick answer A generated client that only models successful responses leaves your error handling untyped. Most generators turn 2xx schemas into clean return types but collapse every 4xx and 5xx
Read article