Author

Powerduck

4 min read

How to document webhooks in OpenAPI 3.1 (with signatures, retries, and examples)

Webhooks are reverse APIs: your server is the client, so the documentation has to cover payloads, delivery ordering, retries, signature verification, and endpoint registration. OpenAPI 3.1 made webhooks top-level citizens — here is a complete, consumer-ready webhook definition.

Read article
3 min read

When AI writes your system, who defines what done means?

A booking app built from one prompt can pass every visual check and still fail on time zones, double bookings, and stale cancel responses. Teams need a contract both people and tools can query, change, and verify.

Read article
3 min read

A curl command is not an API handoff

A request that runs is the start of a handoff, not the end of one. Import the curl, capture the missing context, and promote what you learned back into the specification.

Read article
4 min read

How to test Server-Sent Events endpoints: curl, Postman, and spec-driven SSE testing

SSE looks like HTTP until you try to test it: the connection stays open, events have names and ids, heartbeats hide disconnects, and ordinary API clients hang. Here is how to test streams with curl, what Postman does and does not do, and how to make SSE scenarios repeatable from an OpenAPI spec.

Read article
4 min read

Cursor vs offset pagination: what to actually put in your OpenAPI spec

Offset pagination is easy until data changes under the client; cursors are stable but opaque and bad for jump-to-page. Here is how to choose, how to document each style in OpenAPI 3.2, and the response envelope that stops frontend teams guessing.

Read article
4 min read

Swagger 2.0 to OpenAPI 3.x migration: a field-tested checklist

Automatic converters handle the mechanical 80 percent and quietly break the other 20: nullable fields, consumes/produces, body parameters, security definitions, and examples. Here is the migration checklist that actually gets a 2.0 spec to 3.2 without lying to consumers.

Read article