Design and specification
Resource modelling, an OpenAPI spec agreed before implementation, and a consistent envelope for errors, pagination and filtering.
Web & Application Development
API design & development
An API is a contract, and most of its cost lands after launch. Renaming a field is trivial in a codebase and expensive in a public API, so the design decisions made in the first week determine how much pain arrives in year two.
Good APIs are boring: consistent naming, predictable pagination, one error format everywhere, and documentation generated from the code so it cannot drift. That is what I aim for, whether the consumer is a mobile app, a partner, or a frontend built by someone else.
How I work on it
Process
Adjusted to the job, but this is the shape it usually takes.
-
Spec first
The OpenAPI document is written and reviewed before code. It is far cheaper to argue about a field name in a YAML file.
-
Mock for the consumers
A mock server from the spec so client work starts immediately rather than waiting on the backend.
-
Implement against contract tests
Tests assert the documented behaviour, so the documentation cannot quietly become fiction.
-
Publish real docs
Generated reference plus hand-written guides, authentication, a first request, and the three things people always get wrong.
Questions
Things people ask
Additive changes go out unversioned, new optional fields break nobody. Anything that removes or changes the meaning of a field gets a new version, with the old one supported for an agreed window and a deprecation header on responses so client developers see it in their logs.
Idempotency keys so a retry cannot double-charge, timeouts on every call, exponential backoff, and storing the raw response. When a provider disputes what happened, the raw payload settles it.
Yes. The reference is generated from the spec, and I write the narrative parts by hand. Those are the bit that determines whether someone integrates in an hour or gives up.