$ cat choices/api-first.md
the call
Build the open API first, dogfood it as your own product's backbone, then invite others onto it. Integration leads to expansion. Every team that builds on your API makes your product harder to leave and bigger than you could grow it alone. The API is the product surface, not an afterthought bolted on for partners.
When the API comes first, your own apps are just its first client. The contract gets battle-tested by the people who can’t ignore its flaws: you. That discipline produces an API good enough to hand to outsiders. And once you do, integration becomes a growth engine. Every partner who wires your API into their workflow extends your product into places you’d never have staffed, raises switching costs, and turns your platform into infrastructure other people build businesses on. You stop growing only as fast as your own roadmap.
API-first is a cost paid up front: versioning, backward-compatibility, docs, auth, rate limits, support. A public contract is a promise you can’t quietly break. For a pre-product-market-fit app still changing shape weekly, that promise is premature; you’d be stabilizing an interface to a thing that isn’t stable yet. Open the API when there’s something worth integrating with and a reason for anyone to integrate, not as cargo-cult “platform” ambition before the product earns it.
GigSmart runs a public developer API at developers.gigsmart.com, and that’s the pattern done right: the same API the product runs on is the one partners build against, so it’s dogfooded into being trustworthy before anyone outside depends on it. A marketplace especially lives on this. The more ways work and workers can flow in and out through integrations, the more valuable the network gets. Integration isn’t a side feature there; it’s how the thing expands.— see: developers.gigsmart.com · works / GigSmart
Design the boundary as if a stranger will depend on it, because the best way to keep an interface honest is to make it public and use it yourself. An API you dogfood and expose is a forcing function for clean contracts, real docs, and stable shapes. An internal-only interface rots toward “whatever the one caller needs this week.” Build the surface others can grow on, and growth stops being something only you can do.
the gaps — what it costs even when it’s right
A public API is a promise you can’t take back. Once partners depend on a shape, you own backward-compatibility and deprecation forever. Versioning and migration become permanent line items, not one-time work.
It’s a support and trust surface, not just code. Docs, sandboxes, status, auth, rate limits, and someone to answer “why did this 400?” The API is a product, and products need owners. Ship it half-staffed and it erodes the trust the integration strategy depends on.
Premature openness freezes a moving target. Lock a contract before the product knows what it is and you’ll either break partners later or let a bad early shape calcify. The leverage is real only after there’s something stable worth building on.