Design Patterns API Gateway

An API Gateway acts as a single front door for a group of backend services. Clients send every request to the gateway, and the gateway routes each one to the right service. Applications built from many small services stay simple for their clients.

The Real-World Analogy

A hotel front desk serves guests who need room service, laundry, a taxi, or a restaurant table. Guests call one number. The desk knows which department to contact, checks the guest's room number, and returns the answer. Guests never memorize extension lists.

Problem Without a Gateway

 ┌──────────┐ ────────▶ Orders Service      (address 1, login rules 1)
 │  Mobile  │ ────────▶ Payments Service    (address 2, login rules 2)
 │   App    │ ────────▶ Catalog Service     (address 3, login rules 3)
 └──────────┘ ────────▶ Reviews Service     (address 4, login rules 4)

Client knows every address. A service move breaks every client.
Each service repeats login, logging, and limits.

Solution With a Gateway

 ┌──────────┐        ┌───────────────┐ ───▶ Orders Service
 │  Mobile  │ ─────▶ │  API Gateway  │ ───▶ Payments Service
 │   App    │        │ route + secure│ ───▶ Catalog Service
 └──────────┘        └───────────────┘ ───▶ Reviews Service
 ┌──────────┐               ▲
 │   Web    │ ──────────────┘
 └──────────┘

Clients know one address. Services stay free to move, split, or change their internal layout.

Main Jobs of a Gateway

Routing

Matches a request path to a service. A request to /orders goes to the Orders service.

Authentication

Checks the caller's identity once at the entrance. Services behind the gateway trust the verified identity.

Rate Limiting

Caps how many requests a client may send per minute. The limit protects services from overload.

Aggregation

Combines several service answers into one response. A product page might need catalog data, reviews, and stock levels in a single reply.

Translation

Converts protocols or formats between clients and services.

Request Flow With Aggregation

Client: GET /product-page/42
          │
          ▼
     API Gateway
      ├──▶ Catalog Service   → name, price
      ├──▶ Reviews Service   → rating
      └──▶ Stock Service     → 12 left
          │
          ▼ merges three answers
Client receives one response

Code Example

class ApiGateway {
    private Map routes = new HashMap();
    private TokenChecker checker;
    private RateLimiter limiter;

    ApiGateway() {
        routes.put("/orders",   new OrdersClient());
        routes.put("/payments", new PaymentsClient());
        routes.put("/catalog",  new CatalogClient());
    }

    Response handle(Request request) {
        if (!checker.isValid(request.token)) {
            return Response.unauthorized();
        }
        if (!limiter.allow(request.clientId)) {
            return Response.tooManyRequests();
        }
        ServiceClient target = routes.get(request.pathPrefix());
        if (target == null) {
            return Response.notFound();
        }
        return target.forward(request);
    }
}

Related Patterns

Pattern	Connection
Facade	Gateway acts as a Facade for services over a network
Proxy	Gateway forwards calls on behalf of services
Chain of Responsibility	Security, limits, and logging run as chained steps
Circuit Breaker	Gateways commonly use breakers for failing services

Design Cautions

• A single gateway can become a bottleneck. Run several copies behind a load balancer.
• Business rules inside the gateway create a hidden monolith. Keep it focused on routing and cross-cutting needs.
• Separate gateways per client type, such as mobile and web, keep each one lean.

Advantages and Disadvantages

Advantages	Disadvantages
One simple entry for clients	Extra network hop
Shared security and logging	Single point of failure without redundancy
Freedom to reshape services	Extra component to operate

Step-by-Step Walkthrough

Follow handle() in the code example. A request arrives with a token and a path. The gateway checks the token and rejects invalid ones. A rate limiter counts the request against the client's allowance. Route-table lookup finds the Payments client, and the gateway forwards the request.

The gateway returns the service reply to the caller. Clients saw one address throughout, and the Payments team stays free to relocate its service.

Gateway Per Client Type

Mobile phones, web browsers, and partner systems have different needs. A mobile gateway returns compact data to save bandwidth, while a partner gateway enforces strict contracts. Separate gateways keep each one simple. Teams call this layout the backend-for-frontend approach.

Common Mistakes

• Placing business decisions inside the gateway.
• Skipping timeouts, which lets slow services stall every client.
• Running a single gateway copy with no backup.

Key Takeaways

• An API Gateway gives clients one entry point to many services.
• It handles routing, authentication, rate limits, and aggregation.
• Keep business logic out of the gateway.
• Run redundant copies to avoid a single point of failure.