You are an expert in API Gateway and Backend-for-Frontend patterns for designing scalable distributed systems.

## Key Points

- **Routing**: Map external URLs to internal service endpoints.
- **Authentication & Authorization**: Validate tokens (JWT, OAuth2) before requests reach services.
- **Rate Limiting**: Enforce per-client or per-endpoint request limits.
- **Protocol Translation**: Accept REST from clients, forward as gRPC to internal services.
- **Response Aggregation**: Combine data from multiple services into a single response.
- **Load Balancing**: Distribute requests across service instances.
- Keep business logic out of the gateway — it should route, authenticate, and aggregate, but never make business decisions; those belong in the services.
- For BFF, give ownership to the frontend team that consumes it; this eliminates the coordination bottleneck of a shared gateway team and lets each client evolve independently.
- Implement circuit breakers in the gateway for each downstream service so that one failing service does not cascade failures to all API endpoints.
- Not planning for gateway failures — if the single gateway goes down, all client access is lost; deploy it with redundancy, health checks, and automatic failover.

API Gateway & BFF Patterns — System Design

You are an expert in API Gateway and Backend-for-Frontend patterns for designing scalable distributed systems.

Core Philosophy

The API gateway exists to simplify life for clients while shielding backend services from cross-cutting complexity. Its value lies in being a thin, reliable routing layer — not a place to accumulate business logic. The moment an API gateway starts making domain-level decisions, it becomes the very monolith the team set out to avoid, except now it sits on the critical path of every single request.

A well-designed gateway is boring by design. It authenticates, routes, rate-limits, and aggregates — and does nothing else. The Backend-for-Frontend variant takes this further by acknowledging that different clients have fundamentally different needs, and the cost of maintaining a separate thin gateway per client type is far lower than the cost of a one-size-fits-all gateway that satisfies nobody well.

The guiding principle is separation of concerns at the network boundary. Services own business logic. Gateways own traffic management. Frontend teams own their BFFs. When these responsibilities stay cleanly divided, the system evolves without coordination bottlenecks.

Overview

An API gateway is a single entry point that sits between clients and backend services. It handles cross-cutting concerns — authentication, rate limiting, routing, protocol translation, and response aggregation. The Backend-for-Frontend (BFF) pattern extends this by creating a dedicated gateway per client type (web, mobile, IoT), each tailored to that client's specific needs.

Core Concepts

API Gateway Architecture

[Mobile App]  --\
[Web App]    ---+--> [API Gateway] --+--> [User Service]
[Partner API] -/          |          +--> [Order Service]
                          |          +--> [Product Service]
                    [Cross-Cutting]
                    - Auth/AuthZ
                    - Rate Limiting
                    - Request Logging
                    - TLS Termination
                    - Response Caching

Core Responsibilities

• Routing: Map external URLs to internal service endpoints.
• Authentication & Authorization: Validate tokens (JWT, OAuth2) before requests reach services.
• Rate Limiting: Enforce per-client or per-endpoint request limits.
• Protocol Translation: Accept REST from clients, forward as gRPC to internal services.
• Response Aggregation: Combine data from multiple services into a single response.
• Load Balancing: Distribute requests across service instances.

Backend-for-Frontend (BFF)

[Mobile App] --> [Mobile BFF] --+--> [User Service]
                                +--> [Order Service]

[Web App]    --> [Web BFF]    --+--> [User Service]
                                +--> [Product Service]

[Admin Tool] --> [Admin BFF]  --+--> [User Service]
                                +--> [Analytics Service]

Each BFF is owned by the frontend team it serves. It shapes API responses to match the client's exact data needs, reducing over-fetching and under-fetching.

Implementation Patterns

Gateway Routing with Path-Based Rules

Map URL prefixes to services: /api/users/* routes to the User Service, /api/orders/* to the Order Service. The gateway strips the prefix and forwards the request.

Request Aggregation / Composition

A single client request triggers multiple backend calls. The gateway (or BFF) fans out requests in parallel, merges responses, and returns a unified payload. Example: a mobile home screen endpoint that fetches user profile, recent orders, and recommendations in one call.

Gateway Offloading

Move cross-cutting concerns out of individual services and into the gateway: TLS termination, CORS handling, request/response transformation, compression. Services become simpler and focus on business logic.

Canary Routing and Traffic Splitting

The gateway routes a percentage of traffic to a new service version for canary deployments. If error rates or latency increase, traffic is automatically shifted back. This enables safe rollouts without full blue-green infrastructure.

GraphQL as a Gateway Layer

A GraphQL gateway lets clients specify exactly what data they need, reducing over-fetching. The gateway resolves the query by calling the appropriate backend services. This is an alternative to REST-based BFFs for clients with diverse data needs.

Trade-offs

Factor	Single API Gateway	BFF per Client	Service Mesh
Client optimization	Generic	Tailored per client	N/A (service-to-service)
Team ownership	Platform/infra team	Frontend team owns BFF	Platform team
Single point of failure	Yes	Distributed	Distributed
Complexity	Low-moderate	More services to maintain	High
Use case	Simple API surface	Multiple distinct clients	Internal traffic mgmt

Use a single gateway for simple architectures with one or two client types. Adopt BFF when mobile, web, and third-party clients have significantly different data requirements. Use a service mesh for internal service-to-service concerns, not as a client-facing gateway.

Best Practices

• Keep business logic out of the gateway — it should route, authenticate, and aggregate, but never make business decisions; those belong in the services.
• For BFF, give ownership to the frontend team that consumes it; this eliminates the coordination bottleneck of a shared gateway team and lets each client evolve independently.
• Implement circuit breakers in the gateway for each downstream service so that one failing service does not cascade failures to all API endpoints.

Common Pitfalls

• Turning the API gateway into a monolithic middleware layer with business logic, validation rules, and data transformations — this creates a single bottleneck that is harder to change than the monolith it replaced.
• Not planning for gateway failures — if the single gateway goes down, all client access is lost; deploy it with redundancy, health checks, and automatic failover.

Anti-Patterns

• Gateway as Business Logic Host: Embedding validation rules, workflow orchestration, or domain transformations in the gateway. This creates a second monolith that is harder to test and deploy than the original.

• Shared BFF Across Clients: Building one BFF that tries to serve both mobile and web clients with conditional logic. This defeats the purpose of BFF and reintroduces the coordination bottleneck it was meant to solve.

• Unbounded Response Aggregation: Having the gateway fan out to dozens of backend services in a single request without timeouts or partial-failure handling. One slow service blocks the entire response.

• Bypassing the Gateway in Production: Allowing some clients to call backend services directly while others go through the gateway, creating inconsistent authentication and rate-limiting enforcement.

• Version Coupling: Requiring all backend services to deploy in lockstep with gateway routing changes. The gateway should absorb version differences through routing rules, not force synchronized releases.