Back to all articles
APIs as a ProductPart 02
API productsPlatform strategyAPI designSystem design

APIs as a Product, Part 2: One Core, Many Doors

Janahan Thavendran4 min read

TL;DR

  • Point-to-point integrations duplicate business rules and tie every product and partner to the slowest release cycle.
  • A common core API layer for loyalty, menus, transactions, catalog and payments sits behind two doors: an internal surface and a partner and open API surface.
  • Each domain has to get the shared core right, from ID mapping to cached loyalty balances and honest order states, and the core is versioned once for everyone.
In this article

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.

Internal products and partners reach one core through two doors
Internal door
Internal products
Ordering app, loyalty, other teams
Internal API surface
A common contract: products call the core, not each other
Partner door
External partners
Named partners and open developers
Partner and open API surface
Partner contracts, auth, rate limits, certification before go-live
Core APIs
Loyalty, menus, transactions, catalog and payments. One source of truth per domain, versioned once.

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.

core API layer · two surfaces, one core

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.