From Integration to Product

An insurer that opens its business processes to brokers or aggregators through APIs, changes the nature of what it offers. Once a broker builds its user journeys and internal processes on the insurer's API, that API stops being integration plumbing and becomes a product that other organizations depend on. Those third parties build against the API's contract, and a service-level agreement states what the insurer commits to: availability, support, and how and when the API contract may change. A product of that kind has to be designed, kept stable and owned, and each duty places distinct demands on the insurer.

Who Designs the Product?

At first glance, the obvious party to design an insurer’s partner APIs is the vendor of the back-end system that holds the data. They know the system, often ship an API of their own, and can deliver quickly. The difficulty is that a vendor designs inside out, starting from the system they know and exposing their data model, its vocabulary, its module boundaries and its release calendar. The resulting API contract is technically sound but describes the insurer’s internal systems rather than its business functions. A broker that integrates against it must learn how the vendor models a policy, and every quirk of that model becomes part of the API contract and hence the broker’s code.

Product design works from the outside in. It starts with what the partner needs to get done, identifies the business capabilities that serves that need, and shapes the contract around those capabilities, whatever system happens to implement it today. Design thinking is an established methodology in digital UX design, and its principles are equally applicable to API design. It demands the designer to understand the consumer, here both the broker’s developers and the broker’s business, and to shape and test the API contract with them before anything is built. When using this method with APIs, it implicitly leads to applying the commonly accepted architectural principle “contract-first design”: The contract must be agreed before any code is written, and the implementation is made to conform to the contract.

A contract written during or after the build only documents whatever the implementation turned out to be, which is inside-out design again. An insurer can outsource the build of its APIs. It cannot outsource the design of its product, including its API products.

The Most Stable Thing an Insurer Owns

Once the API product is designed, consumers expect it to stay put, so a broker contract should move only when the move is worth something to them. Every change to a contract that a broker has already integrated costs the broker analysis, development, testing and a release of its own. Where the business case for the change sits entirely on the insurer’s side, the broker carries that cost for no return.

Behind the contract, the insurer’s landscape does not stand still. Vendors ship releases, core systems are replaced, products are launched and retired, and a transformation roadmap reorganizes internal applications that brokers have never heard of. The insurer wants its internal pace of change to be as fast as possible, and its API partners want the external pace to be as slow as possible. Without an architectural answer these two positions collide, and either internal change turns into a negotiation with brokers or commitments to brokers slow the roadmap down.

The Three-Layer Model, Read for Partner APIs

The three-layer model, also known as “API-led connectivity”, was devised to let parts of a landscape change at different paces. The model separates the work of an integration into three concerns and assigns each to a layer, conventionally drawn with systems of record at the bottom and consumers at the top. A System API, at the bottom, unlocks a system of record and publishes its operations in a standard, predictable form, whatever protocol that system speaks. A Process API in the middle composes operations from several systems, and the decisions between them, into one business operation – for example a quotation API that draws on more than one back-end. An Experience API at the top presents a business capability to one class of consumer, such as brokers, and holds the partner contract stable.

The model also prescribes the direction of dependencies, and this is where partner APIs turn things around. An API may depend only on APIs that change less often than it does. The standard rule assumes that consumer-facing APIs change fastest, because channels and user journey features come and go, and that systems of record change slowly. This paradigm is inspired by Gartner’s “Pace Layered Application Strategy”. For partner APIs the assumption is reversed. The partner contract is the slowest-changing component in the estate, held in place by the partner agreement, while the systems beneath it move on a vendor’s roadmap or a transformation plan. Dependencies still point downward, because the partner API has to call the systems that hold the data, but downward now leads toward the more volatile side. A broker contract fixed for years stands on a core system scheduled for replacement. The rule can no longer be met.

Our reading is that this reversal changes what each layer is intended for. It doesn’t invalidate the model, nor does it make the model unfit for insurers. In the textbook case they let the top move quickly over a stable base; for partner APIs they have to hold the top still. An API placed between the partner contract and a fast-moving back-end can do one of two things with a change beneath it. It can absorb the change, translating it into a contract that does not move, or it can pass the change up to every partner.

Absorbing change is the main reason to deploy an API between partner and back-end. In its simplest form, a System API mirrors the system it unlocks, translates little more than the protocol and vocabulary, and absorbs nothing. A renamed field or a restructured code list then lands in the mapping inside the System API, and its own contract holds, together with everything built on it. An Experience API absorbs in the same way at the top of the model, mapping into the partner contract whatever the APIs beneath it publish. When the partner contract itself has to move, the Experience API can run two major versions side by side, so that partners migrate on their own timetable.

How Many Tiers Does a Flow Need?

If an API earns its place between partner and back-end by absorbing change, the next question is how many such APIs a flow actually needs. Answering it requires separating two things that the usual drawing of the model merges into a single box. A role is a responsibility a flow needs: unlocking a system of record, composing a business operation, or holding the contract toward a consumer. A tier is an API that somebody deploys to carry one or more of those roles, and every tier adds a hop to the call path. Each layer of the model names a role, while the number of tiers that carry those roles is a separate decision, taken per flow.

A flow can need all three roles and still be served by one or two tiers. A vendor’s own interface can carry the System role without an API in front of it, provided it already speaks a standard protocol and can be reached from where its consumers run. An Experience API can likewise carry the Process role when the composition is read-only, assembling a response from two calls without deciding anything. The two positions architects usually argue over, “we need three layers” and “we do not want three hops”, can then both be true.

Each tier carries its own cost for the whole of its life. It has to be designed and built, regression-tested against every change beneath it, and operated and monitored. It also adds latency and one more dependency to a landscape in which a single change already reaches too far. A layer costs nothing until somebody deploys an API on it; the cost arrives with the tier.

Sometimes the landscape forces that purchase. A back-end that publishes only a proprietary protocol, or that cannot be reached from where its consumers run, needs a System API whether anyone wants one or not. Leaving it out is as much a defect as deploying a tier that only relays what another tier already carries. Where the landscape forces nothing, a tier is a choice, justified by a benefit that can be evidenced for this specific flow, such as a planned replacement of the back-end or a second consumer for the same composition. Where nobody can name what would fail without the tier, it is not deployed. The burden of proof lies with the tier.

A tier that has been bought still delivers its benefit only when it is built in a particular way. That is the job of a layering standard, the document that says when a tier is deployed and how it must be built. The standard pairs each benefit with the rules that secure it and states, for each rule, what breaks when it is violated. That statement doubles as the test of whether the benefit is real. Two example rules for the Experience API show how the pairing works.

The first is that every field name, code value and error code in the partner contract is chosen by the insurer, and nothing from a back-end is relayed unmapped. It protects the decoupling of the two paces. A single breach, such as passing a vendor’s code list through verbatim, means that the next vendor release that adds a value to that list changes the contract partners see. The tier deployed to absorb exactly that change has failed to absorb it. The larger, strategic cost is that every partner that integrates has to learn the vendor’s model, so the insurer’s vendor lock-in becomes its partners’ lock-in, and replacing the core system later breaks every broker integration at once.

The second is that the Experience API holds no business rules. Read-only composition is permitted, but deciding whether a request is acceptable is a business rule, and it belongs in the back-end that owns it or in a Process API. Business rules change at the pace of the business, whereas the Experience API moves only on its partners’ timetable. A rule placed there turns every change to it into a release of the partner-facing API, with regression risk against a contract the insurer has promised to keep stable. The business then changes at its partners’ pace, and the rule sits out of reach of the process owner who is supposed to govern it.

An Owner for Every Contract

The rules of a layering standard protect a contract only if someone is entitled to enforce them. The owner of an API contract is whoever can refuse a change to it. That refusal is a business decision, because it settles what the insurer promises each partner, which partners may see what, and for how long a version will be supported. Where no owner is named, the team that builds the API becomes the owner by default. That team can judge whether a change is feasible, but the commercial relationship with the integrating partners sits with the business, so the decision ends up with people who do not hold that relationship. Ownership drifts further still when the vendor sets the terms. A partner API whose fields follow the vendor’s model, and whose changes follow the vendor’s release calendar, is a product the insurer does not own, whoever is named as its owner on paper.

The need for a named owner holds for every API contract, not only the one facing partners. Every API the insurer deploys should expose a business capability in the insurer’s own vocabulary, a System API included. Every business capability has a clear owner in the organization. An API for which no single owner can be found is usually cut at the wrong granularity. It spans capabilities that belong to different owners, or it mirrors the structure of a system instead of a capability of the business.

The Model in Its Place

The three-layer model earns its cost in an insurer’s integration estate only by what it does for the product. An insurer that designs its partner APIs itself, outside in and contract first, and names an owner for every contract can use the model for what it does well: keeping the API product stable while the landscape behind it moves. Each tier the insurer deploys toward that end has to justify its own cost.

If you want to learn more about API strategy and architecture, do not hesitate to reach out to thewave.