The 409 Conflict Was a Stale Version Field, Not a Duplicate Request
Quick answer: A 409 Conflict on an update is almost never "the server is broken." It is the server telling you that the resource changed between the moment
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 guidesThe Agent Added a Second Copy of a Utility the Repo Already Had
Quick answer: When an agent adds a "small helper" that already exists elsewhere in the repo, you don't just have a duplicate file. You now have
Read articleMocking Conditional Requests: ETags and 304 Not Modified
Quick answer: A mock that always returns 200 with a full body never exercises the conditional-request path, so a client bug in If-None-Match or ETag handling stays hidden until production.
Read articleResetting Mock State Between Tests for Real Isolation
Quick answer: Stateful mock servers are shared infrastructure, and if one test leaves stubs, counters, or scenario state behind, the next test starts from an unknown condition and fails for
Read articleMocking Third-Party APIs: Keeping External SaaS Out of Local Tests
Quick answer: Local and CI tests should never depend on a live third-party SaaS, because its availability, rate limits, and data are outside your control and a flaky vendor turns
Read articleGenerating an API Changelog Automatically from Spec Diffs
Quick answer: A reliable API changelog is generated by diffing two versions of the OpenAPI spec and classifying each change as breaking, non-breaking, or a deprecation, rather than maintained by
Read articleKeeping Docs in Sync: Regenerating on Every Spec Change
Quick answer: Documentation stays accurate only when regeneration is wired into the same pipeline that changes the spec, not when it depends on a person remembering to rebuild the docs
Read articleTesting gRPC Services: A Client GUI vs a Contract-Driven Flow
Quick answer: A GUI gRPC client is the right tool for exploring a service and sending a request by hand, but it is not a regression strategy: the saved calls
Read articleTesting GraphQL: A Collection of Queries vs Schema-Driven Checks
Quick answer: Testing GraphQL by saving a collection of hand-written queries in a client GUI proves that those specific requests work today, but it does not prove the client respects
Read articleMCP Server Observability: Self-Hosted Logs vs a Registry Black Box
Quick answer: When an MCP server runs through a hosted registry, the operator's view of what the server actually did is limited to whatever logs and metrics the
Read articleVerifying Cursor's Generated Requests Against the Contract
Quick answer: An AI coding assistant like Cursor will happily generate a request that looks correct in the editor but drifts from the actual API contract, because it is working
Read articleTeam API Collaboration Without a Cloud Account
Quick answer: A team can collaborate on API requests and environments without anyone creating a cloud account by storing the request collections, environment templates, and scripts as plain text files
Read article