The Powerduck Blog
Product updates, engineering notes, and guides for designing, debugging, testing, mocking, and serving MCP tools from one OpenAPI spec.
Browse the guidesA written style guide that nobody reads drifts within a month; a Spectral ruleset that fails the build does not. Enforce operationId conventions, tag hygiene, error shapes, versioning, and security coverage with built-in and custom rules, then run them in CI and pre-commit. Here is a practical...
Read articleHardcoding https://api.example.com means the same spec cannot drive a local mock, a staging test, and a production call. Define multiple servers, use server variables for regions and per-tenant subdomains, and set a relative server for serverless and same-origin docs. Here is how codegen, mocks,...
Read articleoperationId becomes the method name in every generated SDK and tags become the namespace and the docs sidebar, yet most specs treat both as afterthoughts. Duplicate ids, verb-first names, and a unique tag per endpoint produce unusable clients and a wall of operations. Here is a naming system...
Read articleDeleting an endpoint is not a deprecation policy, and announcing it once in a changelog does not reach the integrations that actually call it. RFC 8594 gives you the Deprecation and Sunset response headers, Link rel=successor-version points at the replacement, and OpenAPI marks operations...
Read articleAPIs return more than JSON: CSV exports, PDF invoices, ZIP archives, resized images, and generated audio. Model them with the right media type and string/binary schema, document Content-Disposition and Range, and distinguish inline from attachment. Here is how to describe downloads, conditional...
Read articleA search endpoint decays into a pile of ad-hoc query params every client guesses at: filter[status], status_in, q, and a sort string nobody documents. Standardize full text with q, give filters explicit operators and types, use a sign convention for sort, and add sparse fieldsets for payload...
Read articleHolding an HTTP connection open for a three-minute export times out and ties up workers. Return 202 Accepted with a Location to a job resource, model the job state machine, and let clients poll or subscribe to a webhook. Here is the full lifecycle with progress and cancellation, and the OpenAPI...
Read articleLooping 500 POSTs from the client is slow and fails halfway with no way to recover. A bulk endpoint accepts an ordered batch and reports each item independently, including partial success with 207 Multi-Status. Here is the request envelope, per-item status and error arrays, idempotency, and the...
Read articleA network timeout never tells the client whether the charge happened. Retrying a plain POST double-creates; an Idempotency-Key header turns the retry into a replay. Here is the header contract, the in-flight 409 versus the stored response, key lifetime and scope, and the OpenAPI that makes SDKs...
Read articleA timestamp with no offset is ambiguous, a calendar date is not a timestamp, and a duration is not a number of days. Teams conflate all three and silently shift reservations across time zones. Here is the RFC 3339 decision table, when to send an IANA zone versus an offset, and how to model...
Read articleJSON numbers are parsed as doubles, so a 19-digit order id or an exact currency amount can lose digits the moment a client decodes them. Large ids often belong in strings, and money almost never belongs in type:number. Here is the precision table, the string-as-decimal pattern, and what codegen...
Read articleThe server returns id, created_at, and version but must reject them on input; the client sends password and current_password that must never come back. One schema with readOnly and writeOnly properties models both directions and codegen splits it into request and response types automatically....
Read article