API Mediation proposal
| Source | client-resources/API Mediation Proposal.pdf |
| Type | PDF, 8 slides — presentation deck, marked CONFIDENTIAL on every slide |
| Title | API Mediation — Centralized APIs, Intelligent Governance, Seamless Integration |
| Origin | Karnan Seeveratnam, Lead Enterprise Architect · Gopi Balasingam, Chief Architect and Head of Engineering Enablement |
| Dated | 2025-03-15 |
| Status | Circulated for review; whether it was endorsed, funded or superseded is not stated |
What it is
An enterprise architecture proposal for a Manulife-wide API mediation layer, presented as six content slides. It is the only artifact in the corpus that states an enterprise position on API architecture — everything else describes one programme's integration needs. SOW WS 2 names integration and API architecture as a target-state domain, which makes this the closest thing we have to a client-authored starting point for it.
It is also the oldest artifact we hold, by a wide margin. It predates the GARB ADS by eighteen months, the segment assessment and the readiness review by the same, and the June 2026 unified customer architecture by fifteen. Nothing written since cites it, and it cites nothing that came after. It arrived outside the original set of seven — which makes it the concrete answer to open question 5, on whether the input set was complete.
The thesis
Aligning diverse API strategies with centralized governance for seamless customer experience and operational efficiency
Slide 2 states current state as three parallel API strategies already in use — domain-driven API strategy, event-driven architecture, GraphQL-based APIs — with a footer adding REST and MCP. The single named challenge is cross-domain conflicts. Objectives are centralized governance and security, seamless integration and interoperability, enhanced customer experience, and improved API monitoring and management. Benefits claimed: reduced duplication, simplified validation, consistent user experience, higher customer satisfaction, increased integration.
That "consistent user experience" line is the reason this document is in front of us. The proposal's stated justification and the Unified Portal's stated justification are the same sentence, written eighteen months apart by different teams, with no cross-reference in either direction.
Comparative study — slide 3
A fourteen-row table setting centralized against federated API management across control, consistency, scalability, governance, flexibility, implementation, responsiveness, resource allocation, security, operational overhead, innovation, collaboration, cost and use-case suitability. The table makes no recommendation; its last row assigns centralized to "smaller/regulatory-intensive environments" and federated to "large, diverse, innovation-focused orgs".
The recommendation arrives on the next slide instead, in its subtitle: "a proven, centralized mediation model."
The two-tier model — slide 4
The substance of the proposal. Two named mediation tiers, colour-coded in the slide's own legend as centrally managed and federated:
| Tier | Managed | Scope, in the deck's words |
|---|---|---|
| Inter API Mediation Layer | Centralized | "coarse-grained, enterprise-level cross-cutting concerns" |
| Intra-API Mediation Layer | Federated, per LOB | "domain or LOB-specific considerations… delegated to the intra mediation layers" |
The Inter layer is drawn as three gateway sets, each with its own capability list:
| Gateway set | Capabilities as drawn |
|---|---|
| External Ingress API Gateways | Traffic Management · Security · Observability · Transformation · Integration · Productization · Monetization |
| External Egress API Gateways | Subscription/Cost Management · Data Protection · SLA Monitoring |
| Internal API Gateways | Traffic Management · Security · Observability · Transformation · Integration · Productization |
The Intra layer is a service mesh — sidecar proxies carrying traffic management, security, resiliency and observability — instantiated once per line of business. Three are drawn by name: Manulife Bank, Manulife Insurance, Manulife Group Benefit. Beneath each sits a mixed runtime of microservices, miniservices and macroservices on managed container runtimes, VM application servers and legacy monoliths. North-south traffic is mediated by the Inter layer; east-west by the Intra layer.
Above both, a Network-Level APIM Services band: DNS/load balancing, WAAP, DDoS and bot mitigation, ML-based protection, OWASP API Top 10, external API discovery, SASE/SSE and public external API discovery.
To the left, governance is split the same way the runtime is. Externally facing / public external / internal inter-application APIs governance is centralized and carries API standards, a message data structures library, an AuthZ scopes catalog, DDD/bounded contexts, an API catalog and shadow API discovery — plus a collaborative API design toolset and an API CI/CD chain of linting, security scanning, testing, SaC and CAT. Internal intra-application API governance is drawn federated, as a single undecomposed box.
Reference architecture — slide 5
The Inter API Mediation Layer as an enterprise internal API gateway, with its capabilities enumerated and individually marked mandatory or optional by the slide's own legend. The split is the most decision-relevant content in the deck:
| Group | Mandatory | Optional |
|---|---|---|
| Operations | Metrics · Request Tracing · Logging | — |
| Traffic Management | (none) | Rate Limiting · Throttling · Service Routing · Response Caching · IP Allow/Block List · Orchestration |
| Message Handling | Schema Validation · Input Sanitization | Msg Transformation · Protocol Translation · Format Translation |
| Security | JWT Validation · JWT Exchange · Policy Enforcement | JWT Introspection · Policy Enhancement |
Surrounding it:
- Full lifecycle API management (FL-APIM) — internal API dev portal, CI/CD dev enablement, source control holding gateway policies and API specifications, and a management plane the slide itself labels "ClickOps", with its path to the gateway annotated Deploy (manual).
- Governance — centralized governance and management (outer API certification, promote inner API to outer) and asset management (API catalog, API inventory).
- Operations — an enterprise observability platform carrying metrics, traces and logs, feeding a reporting and analytics platform.
- Security and policy enhancement — secrets management; an authorization server doing token validation, token exchange, token introspection, token revocation and certificate updates; and a policy decisioning point. The PDP box's contents are drawn identical to the secrets management box's — "Authorization Server Credentials, Other Credentials" — so the PDP carries no policy artifact, policy language or information point in the reference architecture.
Clients are drawn as web applications, mobile applications and internal services, all entering through the same layer, and the external mediation layer is shown as a separate enterprise external API gateway stack.
Capabilities and future protocols — slides 6 and 7
Slide 6 restates the four capability groups — traffic management, operations, message handling, security — with one-line definitions. Slide 7 is the forward-looking claim: the layer is "designed for future-proofing" and "flexible to support emerging integration protocols seamlessly", with Model Context Protocol as the worked example, positioned as "key protocol enabling context-aware communication" with a "central goal of improved AI and API interaction." Five drivers are named: emerging protocols, MCP, contextual data handling, standardized integration, accelerated AI innovation.
No protocol adapter, schema translation or tool-exposure mechanism is specified for any of this. The claim is architectural intent, not design.
Why it matters here
It is the client-side anchor for R1.1. The deck marks JWT Exchange mandatory at the Inter API Mediation Layer and lists token exchange as an authorization-server function. Manulife's own enterprise API architecture therefore already requires the mechanism the ADS omits and the assessment's B-01 demands — and the API landscape shows it already running in Group Benefits as gb-core-authx, an RFC 8693 service. Proposal, estate and finding agree; only the MVP does not. That is three independent client-side sources, and none of them is ours.
It changes what the MVP's fan-out crosses. The ADS puts eight calls on the login path. Under this model each of them traverses the Inter layer and then the target LOB's Intra layer — two new policy-enforcing hops per call — while rate limiting and throttling, the capabilities that would protect the 25 TPS FCC ceiling, are marked optional.
Its co-author owns open question 8. The Chief Architect is the named owner on which statement of target state is the North Star of record. A proposal from that office, unreferenced by the four documents that followed it, is evidence for the "no agreed North Star" finding rather than against it.
It is not reconciled with the hub-and-spoke estate that exists. The API landscape enumerates two production gateways — PIE-APIM shared across 15+ BU tenants, and GB-APIM dedicated to Group Benefits for a stated reason — carrying roughly 4,200 operations. The deck draws one centralized Inter layer and does not say whether it replaces those gateways, fronts them, or is a logical label for them.
Our review of the proposal is deliverable D2.5, which carries the three areas of improvement and the supporting scenarios.
Open questions raised
- Is this proposal live, endorsed and funded, or superseded? Nothing written in the eighteen months since references it.
- Does the Inter API Mediation Layer replace, front, or rename PIE-APIM and GB-APIM? The answer changes whether this is a migration programme or a governance vocabulary.
- Is the policy decisioning point the PingAuthorize PDP named in the June 2026 strategy, and is the authorization server ForgeRock, PingFederate, or a third thing?
- Why are rate limiting and throttling optional at a layer whose stated purpose is enterprise cross-cutting concerns?
- Does the Inter layer orchestrate? "Orchestration" is listed as an optional Inter-layer capability, and aggregation is exactly what the MVP's Integration API does.
- What is the coexistence and migration path for ~4,200 already-registered operations, and what happens to the deliberate GB-APIM exception?