magnus919_agent-skills/api-design-and-evolution/references/api-infrastructure-topologies.md

# API Infrastructure Topologies

Use this reference when an API decision depends on where traffic enters, crosses, or
leaves a system. Topology supports a contract; it does not define the domain agreement.
Describe the actual path, the responsibility at each hop, and the failure behavior
consumers can observe.

## Traffic Directions

- **North-south:** traffic between clients or external networks and a service estate.
  Common concerns include public admission, identity handoff, rate/resource controls,
  external routing, protocol translation, and partner-facing observability.
- **East-west:** traffic among services, jobs, brokers, and internal control planes.
  Common concerns include service identity, discovery, retries and deadlines, locality,
  load balancing, encryption, dependency policy, and partial-failure containment.
- **Ingress and egress:** name the boundary explicitly. An ingress proxy may admit
  traffic into a cluster or domain; an egress control may govern calls leaving it. Do
  not infer either responsibility from the word "gateway."

## Gateway Versus Service Mesh

Use a gateway or ingress proxy for boundary-facing concerns such as listener and host
routing, external authentication integration, protocol adaptation, public throttling,
request-size limits, cross-origin behavior, and consumer-visible access policy. Keep
domain authorization and contract semantics in the service unless the gateway is an
explicitly governed policy decision point.

Use a service mesh for service-to-service transport concerns such as service identity,
encryption between workloads, discovery, load balancing, traffic shifting, retries,
timeouts, and telemetry propagation. A mesh does not make an unsafe retry safe, prove
business authorization, or define an event's delivery guarantee.

These are tendencies, not mandatory product boundaries. A deployment may combine
functions, use no mesh, or place a control in another proxy. Record who owns each
policy and what happens when the enforcement component is unavailable.

## Map The Request Path

For each important flow, draw or tabulate:

1. caller and trust context;
2. DNS or discovery and route selection;
3. ingress/gateway hops and transformations;
4. mesh sidecars, gateways, or direct service links;
5. service authorization and contract enforcement;
6. downstream calls, queues, or data stores;
7. response, event, or callback path;
8. telemetry and correlation propagation at every boundary.

For each hop record protocol, timeout/deadline, retry owner, load-balancing scope,
buffering, size limit, identity propagation, policy decision, and whether the hop can
duplicate, reorder, delay, or drop work. Never add retries at multiple layers without
an explicit retry budget and operation safety assessment.

## Place Policy Deliberately

Classify a policy as edge, transport, service, or domain policy. Edge policy can
protect a public boundary but may lack domain context. Transport policy can constrain
who may connect and how traffic behaves but cannot replace object/action authorization.
Service policy can enforce resource and operation rules with domain context. Domain
policy decides business invariants and state transitions. Duplicate enforcement only
when the different layers have distinct purposes and failure behavior.

For each policy state the decision owner, source of truth, update path, audit evidence,
fail-open or fail-closed behavior, and stale-policy risk. Route threat modeling and
abuse resistance to `secure-software-engineering`.

## Observability And Failure Boundaries

Define signals at the consumer-visible boundary and at internal hops: request outcome,
latency, saturation, retries, timeouts, rejected policy decisions, route changes, and
correlation/trace continuity. Attribute failures to the narrowest known boundary and
preserve enough context to distinguish an edge rejection, proxy failure, mesh failure,
service failure, dependency failure, and ambiguous completion.

Health checks must reflect the promise they make. A process-level success signal does
not prove that a dependency or route is usable. Document which failures are retried,
which are surfaced, which may have caused work despite an error, and how a consumer
reconciles uncertain outcomes. Coordinate SLO and incident operations with
`site-reliability-engineering`; do not create platform runbooks here.

## Topology Change

Before moving a route, adding a proxy, or introducing a mesh, compare the old and new
paths for contract-visible changes: headers, status mapping, timeout, retry, ordering,
source identity, body limits, caching, streaming support, and telemetry. Use a staged
coexistence path where feasible. Prove the deployed boundary, rollback or pause trigger,
and recovery of in-flight or ambiguously completed work. A topology migration does not
authorize a contract change without the compatibility workflow.

## Topology Exit Check

Stop when traffic direction and paths are explicit, each concern has an owner, policy
placement and unavailable-component behavior are documented, observability crosses the
relevant boundaries, failure and retry multiplication are bounded, and any contract
impact has a separate compatibility assessment.