R6.2 · Centralize the contract, federate the implementation

Theme	R6 · Open decisions
Domain	Integration and API architecture
Status	Proposed
Needs client validation	Yes
Reinforces	R4.1 — what the central tier must enforce · R4.3 — the order it arrives in
Anchored in	The API Mediation proposal's slide 3 comparative study, slide 4 two-tier model and governance column · the API landscape's two-gateway estate
Open questions	Takes a position on 36; depends on 29 and 30
Deliverables	D2.1 · D2.5

Concern

The API Mediation proposal sets centralized against federated API management across fourteen rows and makes no recommendation. Its own last row splits the answer by organisation type: centralized suits "smaller/regulatory-intensive environments", federated suits "large, diverse, innovation-focused orgs". Manulife Canada is both, so the table does not resolve.

The recommendation arrives on the next slide anyway, in its subtitle — "a proven, centralized mediation model" — and the slide under that subtitle draws something else. It draws two tiers: a centrally managed Inter API Mediation Layer for "coarse-grained, enterprise-level cross-cutting concerns" and a federated per-LOB Intra service mesh, colour-coded as such in the deck's own legend. The word and the drawing disagree, and the word is what gets quoted.

The estate underneath is already federated, deliberately. The API landscape enumerates PIE-APIM shared across 15+ business-unit tenants and GB-APIM dedicated to Group Benefits for a stated reason, carrying roughly 4,200 operations between them.

Recommendation

Adopt the two-tier model the deck already drew, and stop calling it centralized. The axis is not one organisation-wide choice. It is a split, and the split runs between the contract and the implementation.

Centralized — identical everywhere, worthless if varied:

• identity and token handling — JWT validation and exchange, already marked mandatory on slide 5
• the AuthZ scopes catalog
• API standards, linting, and the message data structures library
• catalog, inventory, and shadow-API discovery
• the data classification vocabulary and the redaction obligations attached to it (R4.2)
• the observability schema — trace context, correlation identifiers, and the fields a composed request is required to carry (R5.4)

Federated — domain knowledge, wrong when set centrally:

• the values of rate limits, quotas, timeouts, retry budgets and breaker thresholds. That they exist at all is central, and that is R4.1's position
• east-west routing and resiliency inside a line of business
• service decomposition and API design within a bounded context
• release cadence

The comparative table asks the wrong question

It treats control and flexibility as one dial with an organisation type at each end. Read the rows again by what they are properties of: consistency, governance, security and reduced duplication are properties of the contract. Responsiveness, innovation and flexibility are properties of the implementation. A model that centralizes the first set and federates the second takes both columns — and slide 4 is already that model. The deck answered its own question one slide after asking it and did not notice.

A single word has a failure mode, and the programme already has it

"Centralized" read as a runtime stance rather than a governance one turns the gateway into a change-request queue for six lines of business. That is exactly R6.1's Conway's Law concern, one tier down and enterprise-wide instead of programme-wide. The MVP is already going to have that problem at the BFF. It should not have it twice, in two places, with different owners.

The undecomposed box is the actual gap

The deck's governance column splits the same way its runtime does. Externally facing, public external and internal inter-application API governance is drawn centralized and itemised — API standards, the message data structures library, the AuthZ scopes catalog, DDD and bounded contexts, an API catalog, shadow API discovery, a design toolset, and a CI/CD chain of linting, security scanning, testing, SaC and CAT. Internal intra-application API governance is drawn federated, as a single undecomposed box.

Federated is not ungoverned. That box needs a minimum conformance standard — what an Intra layer must implement to be conformant, verified identically for every line of business — and the standard is a central artifact even though every implementation of it is not. Leaving it empty is how "federated" becomes the word teams use for having no position.

Migration cost is why this has to be a split rather than a target

Roughly 4,200 registered operations across two gateways, one of them a deliberate exception made for a stated reason. A centralized reading implies collapsing GB-APIM's 1,311 operations into a shared tier, which is a migration programme nobody has scoped or funded. The split does not imply it. What the Inter layer actually does to PIE-APIM and GB-APIM is open question 30, and the order it arrives in is R4.3's.

What it changes

Three edits to the proposal, and only one of them is a diagram. Replace slide 4's subtitle with the model the slide draws; decompose the intra-application governance box into a conformance standard; re-argue the mandatory and optional split so the controls that make federation safe are not optional, which is R4.1's fight and this page's reason for picking it.

It makes the proposal usable as a target-state input. D2.1 needs one sentence naming the integration and API model. "Centralized" and the drawing cannot both be that sentence, and today the deck supplies both.

It separates two questions that are being asked as one. Whether the model is centralized is a design question and this page answers it. Whether the Inter layer replaces, fronts or renames the gateways that exist is a migration question, it is open question 30, and it stays open either way.

What we are not recommending

That the Intra service mesh is optional. Per-LOB mediation is the federated half of the model, not a concession to teams that have not adopted the central one.

That lines of business author their own security policy. The OIDC/OAuth profile, scopes catalog and classification vocabulary are central, and R5.2 depends on their being central. Each BU application still owns its client registration, session and transaction rules under R1.1. Federating the values of rate limits is not federating authorization.

A governance body. A conformance standard is an artifact. Who arbitrates it is open question 14's, and SOW §3.0 puts operating model design out of scope.

Dependencies and open questions

• Open question 36 — which model is of record. This page is the position.
• Open question 29 — whether the proposal is live, endorsed and funded. A superseded deck makes this a historical note; a live one makes it the enterprise's API model. The register groups 29, 30 and 37 as one conversation with the deck's co-author, and this item belongs in it.
• Open question 30 — replace, front, or rename.
• The stated reason GB-APIM is separate. The API landscape records that the exception was deliberate and does not record why. The reason is the test case for any model claiming to cover the estate.