R4.1 · Make the mediation layer govern the fan-out, not just observe it
| Theme | R4 · API mediation |
| Domain | Integration and API architecture |
| Status | Proposed |
| Needs client validation | Yes |
| Anchored in | Assessment findings C-01, C-02, D-01, D-03, D-06, L-03, L-04 · the API Mediation proposal slide 5 capability legend |
| Open questions | Depends on 24, 27 and 29 |
| Deliverables | D2.5 area 1 · D2.1 · D3.1 |
| Reinforces | R2.1 and R2.2 — the same failure and the same budget, one tier up |
Concern
The proposal marks every capability that would protect the fan-out optional, and every capability that would watch it fail mandatory.
Slide 5 of the API Mediation proposal marks each Inter API Mediation Layer capability mandatory or optional in its own legend. The split is the concern:
| Group | Mandatory | Optional |
|---|---|---|
| Operations | Metrics · Request Tracing · Logging | — |
| Traffic Management | (none) | Rate Limiting · Throttling · Service Routing · Response Caching · IP Allow/Block List · Orchestration |
All six traffic-management capabilities are optional. The layer is required to observe the fan-out and not required to govern it. There is nothing anywhere in the capability matrix for circuit breaking, bulkheading, timeout budgets or retry budgets — resiliency appears only as a chip inside the per-LOB Intra layer service mesh, which is the wrong side of the boundary for a cross-domain fan-out.
Two new synchronous hops per call, sixteen per dashboard render. L-03 counts eight downstream calls per composition. Under the proposal each crosses the Inter gateway and then the target line of business's Intra layer sidecar. C-01 already computes the MVP at 98.71% against a committed 99.99% — a budget of 52.6 minutes a year:
| Added tiers | Per-tier availability | Added annual downtime | Against the budget |
|---|---|---|---|
| 2 | 99.9% | 17.5 h | 20× the whole budget |
| 2 | 99.99% | 1.75 h | 2× the whole budget |
Two tiers at four nines each consume twice the annual error budget before any application code runs. The proposal publishes no per-hop latency budget and no availability allocation, while the ADS commits to 99% of API responses under 800 ms.
Retry amplification is the failure mode a mediation layer adds for free. Assume one retry at each of the three tiers — the Integration API, the Inter gateway, the Intra sidecar. Independently reasonable; composed, each logical call becomes 2 × 2 × 2 = 8 downstream attempts, and a page load becomes 64. A downstream that has slowed but not failed receives eight times its normal load at the moment it is degrading. Against FCC's documented 25 TPS that converts a recoverable brownout into a sustained outage.
Recommendation
Move the three capabilities that bound a fan-out from optional to mandatory, and publish the budget they enforce. Four commitments, each testable:
Rate limiting, throttling and circuit breaking are mandatory on any path that fans out. Expressed as a per-consumer, per-downstream token budget: the Integration API's aggregate claim on FCC is a configured number, not an emergent one. This is the highest-value single change to the proposal, and the mediation layer is the right place for it — better one enforced ceiling than seven BU APIs each defending themselves against a caller they cannot see.
Publish a per-hop latency and availability budget that sums to the ADS's commitments, with a named owner per hop. If the arithmetic does not close — and at two added tiers it does not close even at 99.99% per tier — then the commitment is wrong, the topology is wrong, or the path must degrade. That is R2.2's argument and R2.1's conclusion, and adding tiers sharpens both rather than answering either.
One coordinated retry budget across the three tiers, not per-tier retry policy. Retries at one tier only, with jitter, a global attempt ceiling, and a circuit breaker that opens on downstream error rate rather than on a fixed count.
Settle JWT introspection policy explicitly rather than leaving it optional. Introspection (RFC 7662) is a synchronous call to the authorization server per request; marked optional on a Highly Confidential surface it will be switched on, and the AS becomes a hard dependency of all eight calls at 20,000 concurrent sessions. The alternative — local validation against cached JWKS with short token lifetimes — trades revocation lag for availability. Both are defensible. Leaving it optional means the trade is made by whoever configures the gateway.
What it changes
The mediation layer acquires an availability commitment of its own. Today the proposal describes capabilities; a published per-hop budget makes the layer accountable for a number, which is what makes it a platform rather than a routing tier.
It gives the FCC ceiling an enforcement point that exists. Open question 27 records that per-tenant APIM rate limits already exist and are the fastest partial answer to the missing volumetry. A mandatory rate limit at the Inter layer is where that number is applied once rather than negotiated seven times.
It adds configuration to the critical path that nobody currently owns. Finding F-04 and open question 14 record that the shared runtime has no accountable owner. A mandatory limit is a number someone must set, review and be paged about.
What we are not recommending
Rejecting the mediation layer on latency grounds. The arithmetic is an argument for a published budget and enforced ceilings, not against the tier. A layer that enforces one limit is cheaper than an unmediated fan-out that enforces none.
Making every capability mandatory. Response caching, IP allow/block lists and service routing legitimately vary by API. The test is whether the capability bounds a shared downstream; those three do not.
Per-BU self-defence instead. Seven BU APIs each rate-limiting an opaque service-principal caller cannot express "the dashboard may take 8 TPS of FCC's 25". Only the layer that sees the whole fan-out can.
Waiting for volumetry to set the first limit. Open question 24 is a prerequisite for the right number, not for having one. A configured limit that is wrong is visible and auditable; an absent one is neither.
Dependencies and open questions
- Open question 29 — whether the proposal is live. This recommendation is moot if it is superseded, and urgent if it is funded.
- Open question 24 — per-BU volumetry and a committed FCC capacity figure with a date. R2.4 argues for planning against the documented 25 TPS until it lands, which is the ceiling this layer would enforce.
- Open question 27 — current per-tenant APIM rate limits, which are the fastest available partial answer and already exist.
- CR-39 — current gateway latency percentiles (p50/p95/p99) and the mediation tier's availability history, if it is deployed anywhere today. With CR-22 and CR-23 that is enough to close the budget.