Stack
The problem I was solving
I needed a reliable way to collect, clean and structure business data from many messy sources and hand it to other tools in a predictable shape. My first instinct, like most people, was to build a nice dashboard. I started with the screens. That was the mistake that taught me the most.
Why I flipped it to API-first
Halfway through, I realised every consumer of this data was a program, not a person clicking buttons: an automation, a scraper, another agent, a future me writing a script at midnight. The UI was a thin afterthought. So I rebuilt the whole thing around a documented API, with the dashboard as just one client of that API rather than the product itself.
- Every capability is an endpoint with a stable contract, not a button buried in a screen.
- The API ships with an OpenAPI spec so an agent can discover and use it without me explaining anything.
- Responses are predictable JSON with the same shape every time, so consumers never guess.
What changed once the API came first
The moment the API was the product, everything downstream got easier. Automations plugged in without screen-scraping. Testing became trivial because I was testing endpoints, not clicking through flows. And when I pointed an AI agent at the OpenAPI spec, it could use BizCollect correctly on the first try, because the contract told it exactly what to send and what it would get back. That was the lightbulb moment: a tool that an AI can understand and operate without hand-holding is worth far more in 2026 than a tool that only a human can navigate.
What I would do differently
I would write the OpenAPI spec before writing a single endpoint, and treat it as the design document. I would also version the API from day one instead of bolting versioning on later. The dashboard can always be regenerated; a broken API contract breaks everyone who depends on you, including agents you have never met.
Lessons learned
- Design the API before the UI. The API is the product; the UI is just one client of it.
- Ship a machine-readable contract (OpenAPI) so agents can use your tool without a human translating the docs.
- Predictable, identical response shapes beat clever ones. Consumers should never have to branch on surprises.
- In an agent-first world, "AI can operate this unattended" is a real feature, not a nice-to-have.