APIs other teams can build against — before we argue about the database.
The consumer mock exists before we argue about the database. Resources, pagination, errors, and idempotency on anything that charges or allocates — plus a changelog so breaking changes are explicit.
The “API” is the database over HTTP
Every column leaked, pagination is folklore, and a retry double-charges.
Resources, pagination, and an idempotency key on money paths — not every column leaked over HTTP.
Order { id, status, lines } — a resource, not the table. Pagination and errors are part of the contract.
Retry safeFrontend, partner, and warehouse scrape the same table
Three consumers, one accidental schema, and a Slack channel named #api-please.
One contract for web, partner, and warehouse. Events for work that must not be a synchronous POST.
GraphQL as a dump of the schema
The graph is the database. Depth limits were a blog post. Mobile is on a prayer.
A graph that matches product language, with depth limits and persisted queries — not a dump of the schema.
A graph that matches product language, with depth limits and persisted queries where they earn their keep.
The work we actually deliver.
OpenAPI or GraphQL contract
A contract consumers can mock before we debate tables. REST when resources are clear; GraphQL when many clients need different shapes.
Auth security will sign off
Keys, OAuth, or both — chosen on purpose, reviewed before we paint status codes.
Partner docs
Docs a partner engineer can use without a Slack channel named after the API.
Idempotency on money paths
Retries do not double-charge. Anything that allocates stock or money is idempotent.
Signed webhooks
Signed payloads, retries you can see, and a dead-letter path. Fire-and-forget is how orders disappear.
Versioned changelog
Breaking changes get a version or a flag. Silent field deletion is not a strategy.
Greenfield, strangle, or events.
Greenfield
The consumer mock should exist before the database debate.
OpenAPI or GraphQL schema, then a server that honors it.
Strangle
Legacy is the source of truth for now.
A facade with a contract, while the old system stays behind it.
Events
Partners and warehouses cannot wait on your request path.
Webhooks and queues with delivery you can prove.
No junior hand-offs after the proposal.
You see the real storefront, not a slide deck.
Launch week is the start of the engagement.
Every page leads to a real conversation.