API-First: Building Software That Survives Its Own Success

The interface you build today will be replaced. The data model and API behind it will not. Build accordingly.

Code on a screen representing an API integration

Most business software is built interface-first: design the screens, then write whatever the screens need. It ships faster and works fine until the second consumer appears — a mobile app, a partner integration, an automation — and there is nothing to consume, because the logic lives in the screens.

What API-first actually means

Define the operations your system performs — create a quote, approve an order, fetch a customer's history — as an interface with clear inputs and outputs, before deciding what any screen looks like. The web interface then becomes one consumer among several, with no special privileges. It is the reasoning behind how we scope and build web applications, and why the discovery phase comes first.

What it buys you

  • Integrations become configuration rather than projects. When a client asks to connect their accounting system, the answer is a day, not a quarter.
  • The interface can be replaced without touching business logic — which matters, because interfaces are replaced roughly every three years and logic is not.
  • Automation is possible without screen scraping or a developer writing a one-off script for every request.
  • Testing gets dramatically cheaper: business rules are testable without a browser.

Getting it right without gold-plating

  1. Design around business operations, not database tables. 'Approve order' is an operation; 'update order status field' is an implementation detail leaking into your contract.
  2. Version from day one, even at v1. Retrofitting versioning onto a live integration is painful and public.
  3. Return errors that a machine can branch on and a human can read. Both audiences matter, and most APIs serve neither well.
  4. Document as you build. An undocumented API is a private API, whatever your intentions were.
  • 3 years typical interface lifespan
  • 1 business operation per endpoint
  • 2 consumers is where it pays off

Frequently asked questions

Does API-first slow down the first release?

Modestly — typically ten to twenty percent more effort on the first version. That cost is recovered the first time you add a second interface or integration, and it compounds afterwards.

REST or GraphQL?

For most business applications, REST with well-designed resources is simpler to build, cache and debug. GraphQL earns its complexity when many different clients need very different shapes of the same data — which is a real problem, but not the common one.

More on this topic: Web & Product.

Keep reading

Want this built for your business? See what we do.