blog
When we set out to build a custom B2B ordering platform for a multi-brand franchise, one of the earliest decisions shaped everything that followed: we built it API-first.
We chose it for practical reasons, not fashion, and it paid off in flexibility, cleaner integrations and a system the client can keep building on for years. What API-first means in practice, why it suits an ordering platform, and where the trade-offs bite: three things worth knowing if you're weighing the same call.
What "API-first" means here
In an API-first (or "headless") architecture, the centre of the system is a well-defined API. The backend's job is to expose business capabilities — products, orders, locations, rules — through that API. Everything else is a client of it.
In our build, that means:
- The store-manager app is a client of the API.
- The head-office admin is a client of the API.
- The automated fulfilment integration talks to the same API and domain.
There's no monolith where the screens and the logic are welded together. There's a clean core, and things that talk to it.
Why we chose it for an ordering platform
One backend, many front ends
An ordering platform is rarely "done". Today it needs a mobile app for store managers. Tomorrow it might need a partner integration, a native app, a reporting dashboard, or a feed into another system. With an API at the centre, each of those is a new client of an existing API, not a rebuild. You design the capability once and reuse it.
Cleaner integrations
The fulfilment integration is a case in point. Because the platform already exposes a well-defined API and a clear domain model, plugging the 3PL in is tidy: order routing and stock sync hang off the same core, rather than being threaded messily through the application. A system built to be integrated with is far easier to integrate. (We dig into that in integrating ordering with a 3PL warehouse.)
Independent evolution
Decoupling the front end from the back end means they can move at their own pace. The store-manager experience can be refined and redeployed without touching the backend, and the backend can evolve behind a stable API. Two smaller, well-bounded problems beat one big tangled one. And because the API is yours, you're never locked into a vendor's platform: the system is something you own and can take in any direction.
Business rules in one place
This is the quiet, underrated benefit. In an API-first system, the rules — required-product enforcement, who's allowed to order for which location, how an order is validated — live server-side, in one place. Every client inherits them automatically. There's no risk of the mobile app and the admin disagreeing about what a valid order is, because neither of them decides: the API does.
Security and validation, server-side
Putting the rules in the API means putting the guarding there too. Authentication, who's allowed to act on which location, and whether an order is even valid are all checked on the server, where they can't be sidestepped by a clever request or a stale client. The front end makes the experience pleasant; it never gets to decide what's allowed. For a system placing real orders against real budgets, that single source of truth is what keeps it trustworthy. Change a rule once and every client, the app, the admin, a future integration, is held to it from that moment.
The stack
For readers who want the specifics:
- Backend: Symfony 7.2 with API Platform 4. It exposes the REST API, handles JWT authentication, runs server-side processing when an order is created, and enforces business rules through custom validators. MySQL underneath.
- Front end: a Remix / React progressive web app that consumes the API. It's installable to the home screen and works offline, important for store managers in low-connectivity stockrooms.
- Operational: error monitoring with Sentry, transactional email for things like password resets, and an admin panel that lets head office manage brands, catalogues, locations and couriers without a developer.
API Platform does a lot of heavy lifting here: it turns well-modelled domain entities into a consistent, documented API, which is exactly what you want as the stable centre of an API-first system.
Documented, and yours to extend
A well-defined API isn't only cleaner to build against, it's cleaner to hand over. API Platform generates documentation straight from the domain model, so the API describes itself: every endpoint and field in one place that can't drift out of date the way a written spec does. That matters for a system meant to last. A new developer, ours or yours, can read what the platform does and start building against it without reverse-engineering old code. It's part of what owning it means in practice: you're never dependent on us to understand your own system. When the day comes to bring development in-house or hand it to another team, that documentation turns the move into a handover rather than a rebuild.
Trade-offs, and when we'd reach for it
API-first isn't free.
- There's more upfront design. You have to think carefully about the API and the domain model before you've shipped a single screen. For a tiny, single-purpose tool, that overhead may not be worth it.
- There are more moving parts. A decoupled front end and back end is two things to build, deploy and reason about, not one.
So when would we reach for it? When the system is going to last and grow: when you expect multiple clients or integrations, when business rules matter and must be consistent, and when you'll keep adding to the platform over years rather than shipping it once and walking away. An ordering platform at the heart of a multi-site business sits in that category. A throwaway internal form doesn't.
The bigger picture
API-first is the decision that lets all the other pieces — the offline store-manager app, the head-office admin, the automated 3PL integration — hang together cleanly and keep growing. It's the spine of the platform.
You can see how it all fits together in our case study: how we built a custom B2B ordering platform for a multi-brand café franchise.
Frequently asked questions
Planning a platform you'll build on for years?
If you're weighing how to architect a system that has to last, serve more than one front end, integrate with other systems, and keep its rules consistent, API-first is usually the decision your future self thanks you for.
Tell us about your project and we'll help you make the architecture choices that fit where you're heading, not just where you are today.
