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.
The same senior engineer from kickoff to delivery.
You see the real storefront, not a slide deck.
Launch week is the start of the engagement.
Every page leads to a real conversation.