API Gateway Patterns

Day 085: API Gateway Patterns

An API gateway is useful when the platform needs one disciplined public edge, not when the team wants a new place to hide business logic.

Today's "Aha!" Moment

Once a system has several internal services, the temptation is to expose them all directly and let clients compose what they need. That can work for a while, but it pushes too much internal topology outward. Now mobile and web clients need to know which service owns which data, how many calls are required for one screen, and how to cope when internal boundaries change.

Keep one example throughout the lesson. The learning platform has clients that need identity, enrollment, billing, and course data. A learner opening the dashboard does not care which internal service currently owns progress, subscriptions, or recommended courses. The client just needs one usable response. That is the pressure that makes an API gateway valuable.

That is the aha. A gateway is not important because it is a reverse proxy with a fancy name. It is important because it creates a disciplined public edge: one place to route requests, adapt API shape to client needs, enforce edge concerns, and insulate consumers from some of the churn of the internal service topology.

But that same central position is dangerous. Because every request passes through it, the gateway becomes an attractive place to dump cross-service logic, workflow decisions, and policy that really belongs to domain services. The lesson is therefore two-sided: gateways are powerful when they own edge concerns, and harmful when they become the new monolith at the front door.

Why This Matters

The problem: Without a coherent edge, internal service decomposition leaks outward into clients. With an overloaded gateway, the edge itself becomes a new coupling hotspot.

Before:

After:

Real-world impact: Cleaner client integration, safer internal evolution, less duplicated edge logic, and fewer cases where the gateway becomes a fragile "god service."

Learning Objectives

By the end of this session, you will be able to:

  1. Explain what an API gateway is actually for - Connect it to public-edge control, client adaptation, and topology shielding.
  2. Reason about what belongs in the gateway - Distinguish edge concerns from domain logic.
  3. Recognize when a gateway pattern fits - Explain when it simplifies the system and when it only adds another hop.

Core Concepts Explained

Concept 1: A Gateway Creates One Public Edge over Many Internal Services

The most basic job of a gateway is to give clients one coherent entry point while the platform behind it remains decomposed.

web / mobile / partner clients
            |
            v
        API gateway
         /   |    \
 identity  catalog  enrollment  billing

This matters because internal service boundaries are usually designed around ownership and runtime concerns, not around what external consumers find convenient. A client should not need to know whether a dashboard screen depends on identity plus enrollment plus billing, nor should it need to change every time the backend reorganizes those internals.

The gateway therefore acts as a boundary translator. It presents a stable public surface while the internal system remains free to evolve more aggressively behind it.

The trade-off is simplification at the edge versus one more infrastructure component in the request path. A gateway reduces client coupling, but it also becomes part of latency, availability, and operability for every routed request.

Concept 2: Gateways Are Strongest at Edge Concerns and Client Shaping

The gateway earns its existence when it handles concerns that are genuinely about the edge:

For the learning platform, the mobile app may want one compact "dashboard" response, while the admin UI may want a richer multi-panel payload. Those are client-facing concerns. The gateway can compose or reshape data so each client does not have to orchestrate the internal graph manually.

mobile dashboard request
    |
    +--> gateway composes:
         profile + active enrollments + subscription summary

This is useful precisely because internal services are not obligated to match client ergonomics one-to-one. Their boundaries are usually shaped by ownership, not by screen design.

The trade-off is convenience versus added latency and complexity at the edge. Aggregation can simplify clients dramatically, but the gateway should stay disciplined enough that shaping does not turn into owning business policy.

Concept 3: The Gateway Becomes Dangerous When It Starts Owning Domain Decisions

Because every request passes through the gateway, it is tempting to put "just one more rule" there. Soon the gateway is not only routing and shaping. It is deciding enrollment eligibility, applying billing policy, checking course-release rules, and stitching together workflow semantics that really belong inside domain services.

That is how a gateway becomes the new monolith:

healthy gateway:
route + adapt + enforce edge policy

unhealthy gateway:
route + adapt + own business decisions for many domains

The warning signs are familiar:

The right mental model is that a gateway manages entrance and translation. It should not become the hidden home of the business. If a rule belongs to billing, enrollment, or catalog, the gateway may call that service or pass through claims and context, but it should not quietly steal the rule.

The trade-off is central convenience versus boundary erosion. A heavy gateway can feel efficient in the short term, but over time it weakens service ownership and creates a new high-blast-radius bottleneck at the system edge.

Troubleshooting

Issue: Adding a gateway that only forwards requests without solving any real client or edge problem.

Why it happens / is confusing: Gateways are common in diagrams, so teams add one by default.

Clarification / Fix: Use a gateway when it creates real value: stable public surface, client adaptation, edge policy, or shielding from internal topology churn.

Issue: Treating the gateway as the right place for all cross-service logic.

Why it happens / is confusing: The gateway is central and sees every request, so it feels like the easiest place to "just put the rule."

Clarification / Fix: Keep the gateway focused on edge concerns. Domain decisions still belong in the services that own the capability.

Issue: Assuming the public API should mirror internal service boundaries exactly.

Why it happens / is confusing: Internal service decomposition is visible to backend teams, so it starts to look like the obvious public API shape too.

Clarification / Fix: Public API design should follow consumer needs and edge semantics, not necessarily internal runtime topology.

Advanced Connections

Connection 1: API Gateways ↔ Backend-for-Frontend

The parallel: A BFF is a stricter version of the same idea, where the edge surface is intentionally tailored to one client class rather than shared generically across all clients.

Real-world case: Mobile apps often benefit from lighter, more aggregated responses than admin or web clients.

Connection 2: API Gateways ↔ Service Evolution

The parallel: A stable edge can absorb some internal service refactors so that clients do not have to track every decomposition or ownership change behind the scenes.

Real-world case: One internal service may become three, or three may collapse into one module, while the public gateway contract remains stable.

Resources

Optional Deepening Resources

Key Insights

  1. A gateway is a public-edge boundary, not just a proxy - Its main value is controlling how clients meet the platform.
  2. Client shaping and domain ownership are different concerns - The gateway can adapt responses without becoming the owner of business rules.
  3. A heavy gateway is a warning sign - If domain logic keeps moving into the edge, the system is rebuilding a monolith in front of the services.

Knowledge Check (Test Questions)

  1. What is one core reason to use an API gateway?

    • A) To provide clients with one coherent public edge instead of exposing internal service topology directly.
    • B) To move all domain logic into a single place.
    • C) To eliminate the need for downstream services.

  2. When is gateway aggregation especially useful?

    • A) When a client needs one response built from several internal services and should not orchestrate that composition itself.
    • B) When the system wants to avoid all routing decisions.
    • C) When every internal service already exposes the ideal public API for every consumer.

  3. Why is putting too much business logic in the gateway risky?

    • A) Because it can turn the gateway into a new central monolith and blur domain ownership boundaries.
    • B) Because gateways cannot inspect requests deeply enough.
    • C) Because edge services never need any policy logic.

Answers

1. A: The gateway is most useful when it creates a stable, controlled public edge and hides internal topology from clients.

2. A: Aggregation is valuable when it simplifies the consumer's job without forcing the consumer to understand the internal service graph.

3. A: Once the gateway starts owning domain behavior for many parts of the platform, it weakens the service boundaries the architecture was trying to create.

← Back to Learning