APIs as a Product, Part 2 of 10 · A common API layer for internal products and partners.
Every new partner used to start the same way. Someone listed the systems the partner needed to reach: the menu, the loyalty balance, the order, the payment. Then someone built a connection to each of them, in whatever shape that system happened to expose.
Our own products worked the same way. Loyalty talked to transactions one way, the ordering app talked to menus another way, and payments had its own conventions. The same business rule could live in more than one place. When it changed, it changed in one place first and the others caught up later, if someone remembered.
Nobody designed it like that. It is what happens when every integration is solved on its own deadline.
One core, two front doors
What we built instead was a common core API layer: one set of domain APIs for loyalty, menus, transactions, catalog and payments, with everything else connecting through it. Internal products call the core instead of calling each other. Partners reach the same core through their own front door.
Both doors call the same core, so a change to loyalty, menus or transactions reaches every internal product and partner at once, and is versioned and communicated once.
The two doors look different on purpose. The internal surface gives our own teams a common contract, so a new product doesn't need a private agreement with five others. The partner and open API surface exposes the same core with what outsiders need: partner-facing contracts, authentication, rate limits, and certification before go-live.
Behind both doors sits the same core. That changes what each domain has to get right.
The same pattern in every domain
For menus and catalog, the core is the source of truth. Our products and partners both read from it, partners keep their own ID mappings to it, and a core ID is never reused. A new field, such as a new availability state, can be added without breaking either door.
For loyalty, the core holds points, tiers and redemption rules. The ordering app calls it, and so do bank apps and aggregators. Here a careless change has a face: a partner app that caches balances shows a customer the wrong number of points.
For transactions, the core holds order state and payment state. Both doors depend on those states being honest, so that "accepted" never quietly means "completed". And because the same order can arrive through either door, every call that creates an order or moves money has to be safe to send twice, so a retry can't create a duplicate order or a double charge.
There was a second reason for one core, and it was about time. The core team could ship when a change was ready. Internal teams shipped on their own sprints, against their own priorities. Partners shipped monthly, behind app-store review. Customers updated their apps whenever they felt like it. Point-to-point integrations tied all those clocks together, so the slowest one set the pace for everyone. One core, with each door taking changes at its own pace, let them run apart.
What it costs
A shared core is not free. The core team becomes a dependency for everyone, and a slow core team slows every product. And once internal teams and partners share a contract, you can't change it for one without making a promise to the other. The core has to be versioned once, and that version communicated to everyone who calls it. Part 5 covers how we did that.
I used to describe this work as building an API. It wasn't. It was building one contract shared by everyone who does business with us, inside the company and outside it, and then learning to keep it.
Related reading: what belongs in a shared core and what stays with each product is the subject of The Shared Platform, Part 1.