Enforce an API style guide in CI with Spectral: custom rules that stop bad OpenAPI before it merges
Powerduck
Command Palette
Search for a command to run...
Archive
117 posts published so far
OpenAPI docs renderers compared: Swagger UI, Redoc, Scalar, Stoplight Elements, and RapiDoc on one spec
Powerduck
Health checks for APIs: /healthz, /readyz, /livez, version, and metrics in OpenAPI
Powerduck
Designing a search endpoint in OpenAPI: q, filters, sorting, sparse fieldsets, and pagination codegen understands
Powerduck
File downloads in OpenAPI: CSV, PDF, ZIP, images, Content-Disposition, and non-JSON responses
Powerduck
Deprecating an API without breaking clients: Deprecation and Sunset headers, successor-version, and OpenAPI
Powerduck
operationId and tags in OpenAPI: naming conventions that keep generated SDKs and docs usable
Powerduck
Modeling money and big integers in OpenAPI: int64 precision, decimal amounts, and why number fails for currency
Powerduck
Dates, times, and time zones in OpenAPI: date-time, date, duration, and the timezone mistakes that shift bookings
Powerduck
Idempotency-Key in practice: retrying POSTs safely, deduping concurrent requests, and documenting it in OpenAPI
Powerduck
Bulk and batch API endpoints: modeling create-many, partial success, and 207 Multi-Status in OpenAPI
Powerduck
Long-running REST APIs: 202 Accepted, Location, job status polling, and webhooks in OpenAPI
Powerduck
OpenAPI additionalProperties: modeling maps, dictionaries, labels, and free-form objects without losing types
Powerduck
readOnly and writeOnly in OpenAPI: one schema for create, response, and password fields
Powerduck
Recursive and cyclic schemas in OpenAPI: self-referencing $ref for trees, nested comments, and graphs
Powerduck
OpenAPI enums vs const: closed lists, open-ended strings, and how to add a value without breaking clients
Powerduck
Optional, nullable, or omitted? Modeling missing data in OpenAPI 3.1 without lying to clients
Powerduck
PUT vs JSON Merge Patch vs JSON Patch: modeling partial updates in OpenAPI without the null ambiguity
Powerduck
OpenAPI callbacks vs webhooks: modeling async request/reply with runtime expressions
Powerduck
The JSON Schema constraints that actually work in OpenAPI: format, pattern, ranges, and what codegen and AI mocks do with them
Powerduck
Model polymorphism in OpenAPI 3.1: oneOf, anyOf, allOf, and discriminator without breaking clients
Powerduck
Document rate limits in OpenAPI so clients actually back off: 429, Retry-After, and rate-limit headers
Powerduck
Prevent lost updates with ETag and If-Match: optimistic concurrency in OpenAPI
Powerduck
File uploads in OpenAPI: multipart/form-data, raw binary, and multiple files done right
Powerduck
Stop letting examples lie: make your OpenAPI spec the single source of truth for docs, mocks, and agents
Powerduck