Introduction

A small application can expose one API from one backend service. As the application grows, clients can need to communicate with account, catalog, enrollment, payment, search, reporting, and notification services.

Without a gateway, a client might need to know:

• The public address of every service
• Which service owns each operation
• How every service authenticates callers
• Which API version each service supports
• How to handle service-specific failures
• How to combine results from several services
• How to apply rate limits and request deadlines

This creates tight coupling between clients and the internal service architecture.

An API gateway provides a centralized entry point through which clients access application APIs.

Clients
   |
   v
API Gateway
   |
   +-- Account Service
   +-- Course Service
   +-- Enrollment Service
   +-- Search Service
   +-- Payment Service
   +-- Notification Service

Prerequisites

What Is an API Gateway?

An API gateway is a server or managed service positioned between API clients and backend application services.

It receives API requests through a public or internal endpoint, applies configured policies, selects the appropriate backend, forwards the request, receives the backend response, and returns a response to the client.

API Client
    |
    v
API Gateway
    |
    +-- Authenticate request
    +-- Authorize operation
    +-- Apply rate limit
    +-- Validate request
    +-- Select route and version
    +-- Forward request
    +-- Record telemetry
    |
    v
Backend Service

Why Use an API Gateway?

A gateway provides a stable client-facing boundary even when internal services are introduced, replaced, split, combined, or moved.

Without an API Gateway

Mobile Client
   |
   +-- accounts.example.com
   +-- courses.example.com
   +-- enrollments.example.com
   +-- search.example.com
   +-- payments.example.com

The client knows the internal service decomposition and must communicate with several independently managed endpoints.

With an API Gateway

Mobile Client
   |
   v
api.example.com
   |
   v
API Gateway
   |
   +-- Account Service
   +-- Course Service
   +-- Enrollment Service
   +-- Search Service
   +-- Payment Service

The client uses one stable API entry point while the gateway manages the backend routing.

Common Gateway Responsibilities

• API routing
• Backend load balancing
• TLS termination
• Mutual TLS where required
• Authentication-token validation
• Selected authorization policies
• Rate limiting
• Quotas
• Request-size limits
• Request validation
• Request and response transformation
• API-version routing
• Request aggregation
• Protocol mediation where supported
• Caching where appropriate
• Access logging
• Metrics and distributed-trace context

Exact capabilities depend on the gateway product and deployment model.

API Gateway vs Reverse Proxy

API Gateway vs Load Balancer

Gateway Routing Pattern

Gateway routing exposes several services through one controlled endpoint.

api.example.com/accounts/*
    -> Account Service


api.example.com/courses/*
    -> Course Service


api.example.com/enrollments/*
    -> Enrollment Service


api.example.com/search/*
    -> Search Service

Conceptual Gateway Configuration

gateway:
  routes:
    - id: account-api
      path: /accounts/*
      backend: account-service
      authentication: required

    - id: course-api
      path: /courses/*
      backend: course-service
      authentication: optional

    - id: enrollment-api
      path: /enrollments/*
      backend: enrollment-service
      authentication: required

    - id: search-api
      path: /search/*
      backend: search-service
      authentication: optional

This is conceptual configuration. Exact syntax and policy capabilities depend on the selected gateway.

Gateway Aggregation Pattern

A client screen can require data from several backend services.

Without Aggregation

Client
   |
   +-- Get course details
   +-- Get instructor summary
   +-- Get learner progress
   +-- Get enrollment status
   +-- Get recommendations

With Gateway Aggregation

Client
   |
   v
GET /course-dashboard/42
   |
   v
API Gateway
   |
   +-- Course Service
   +-- Progress Service
   +-- Enrollment Service
   +-- Recommendation Service
   |
   v
Combined response

Aggregated Response

{
  "course": {
    "courseId": 42,
    "title": "System Design"
  },
  "enrollment": {
    "status": "active"
  },
  "progress": {
    "completionPercentage": 72.5
  },
  "recommendations": [
    {
      "courseId": 51,
      "title": "Database Design"
    }
  ]
}

Aggregation can reduce client round trips, but it creates dependency, timeout, response-shaping, partial-failure, and ownership decisions in the gateway layer.

Aggregation Risks

• One slow service delays the complete response
• One failed service can fail the complete operation
• Gateway code can accumulate business logic
• Large responses can increase latency and memory use
• Backend calls can multiply rapidly
• Retrying several dependencies can amplify traffic

Backend for Frontend Pattern

Different client types can require different endpoints, response shapes, and interaction patterns.

Mobile Application
      |
      v
Mobile Gateway


Web Application
      |
      v
Web Gateway


Partner Integration
      |
      v
Partner API Gateway

A Backend for Frontend, commonly abbreviated as BFF, provides a gateway or API layer tailored to one client type.

For example:

• A mobile response can be smaller to reduce transferred data
• A web response can contain a richer page-oriented model
• A partner API can expose stable contract and quota policies
• An administration client can use stricter access controls

Authentication at the Gateway

The gateway can validate credentials or access tokens before forwarding a request.

Client request
      |
      v
API Gateway
      |
      v
Validate credential
      |
      +-- Invalid:
      |      reject request
      |
      +-- Valid:
             attach approved identity context
             forward to backend

Example Request

GET /api/enrollments HTTP/1.1
Host: api.example.com
Authorization: Bearer access-token

The gateway can validate token signature, issuer, audience, lifetime, and other configured requirements.

Authorization Responsibilities

Gateway authorization is useful for broad API access decisions.

Backend services must still enforce domain-level authorization.

Gateway decision:

Caller may use enrollment APIs.


Backend decision:

Caller may view enrollment 981
for learner 1042 in tenant 17.

Forwarding Identity

After authentication, the gateway can forward approved identity information to backend services.

X-Authenticated-Subject: caller-identifier
X-Trusted-Tenant: tenant-17
X-Request-ID: request-correlation-id

Backends should trust identity headers only when requests come through an approved gateway and the gateway replaces any client-provided values.

Another design is to forward the original validated token so the backend can perform its own verification and authorization.

Trusted Gateway Boundary

Public Client
      |
      v
Approved API Gateway
      |
      v
Private Backend Network


Backend accepts trusted identity
context only from the gateway.

Direct public access to backend services can bypass gateway authentication, rate limiting, TLS, request validation, and logging.

TLS and Mutual TLS

An API gateway can terminate public TLS connections.

Client
   |
   | HTTPS
   v
API Gateway
   |
   | HTTP or HTTPS
   v
Backend Service

Gateway-to-backend traffic can be protected with another TLS connection.

Mutual TLS can authenticate both sides of a connection in environments where client or service certificates are required.

Manage:

• Certificate issuance
• Private-key protection
• Certificate rotation
• Trust stores
• Expiry monitoring
• Revocation or replacement procedures
• Backend certificate validation

Rate Limiting

Rate limiting restricts request volume over a configured interval.

Incoming API request
      |
      v
Determine trusted limit key
      |
      v
Check request allowance
      |
      +-- Allowed:
      |      continue processing
      |
      +-- Limit exceeded:
             reject or delay
             according to policy

Rate limits can be scoped by:

• Authenticated caller
• Tenant
• Subscription or API product
• API operation
• Client application
• Approved network identity

Example Rate-limit Response

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 30

{
  "type": "about:blank",
  "title": "Request limit exceeded",
  "status": 429,
  "detail": "The caller exceeded the permitted request rate."
}

Rate Limit vs Quota

Gateway limits protect shared infrastructure. Backend services should also enforce business quotas and resource-specific rules.

Request Validation

A gateway can reject structurally invalid requests before they reach backend services.

Validation can include:

• Required headers
• Allowed HTTP methods
• Content type
• Maximum body size
• Basic schema validation
• Required query parameters
• Supported API version

Request received
      |
      v
Validate method and path
      |
      v
Validate headers
      |
      v
Validate size and format
      |
      +-- Invalid:
      |      return controlled error
      |
      +-- Valid:
             forward to backend

Backends must still validate business rules and must not assume gateway validation makes all request data trustworthy.

Request Transformation

A gateway can transform a client request before forwarding it.

Public request:

GET /api/v1/courses/42


Internal request:

GET /internal/course-service/courses/42

Transformations can include:

• Adding approved headers
• Removing untrusted headers
• Changing an internal path
• Mapping query parameters
• Changing a request representation where supported
• Adding a correlation ID

Response Transformation

The gateway can also transform selected backend responses.

Backend response:

Contains internal field names
and internal service metadata


Gateway response:

Contains the approved public
contract for the client

Heavy transformation can make the gateway difficult to maintain. Prefer clear service contracts and use gateway mediation for controlled compatibility requirements.

API Version Routing

The gateway can route API versions to different backend deployments.

/api/v1/courses/*
    -> Course API Version 1


/api/v2/courses/*
    -> Course API Version 2

Version information can appear in:

• URL paths
• Hostnames
• Headers
• Media types

Version routing should be explicit, documented, observable, and supported by a retirement policy.

Canary Routing

The gateway can route a controlled subset of eligible requests to a new backend version.

Most eligible traffic
    -> Course Service Version 1


Controlled subset
    -> Course Service Version 2

Canary routing requires separate metrics, compatible schemas, rollback criteria, and safe session behaviour.

Gateway Caching

A gateway can cache selected API responses and return them without calling the backend.

API request
    |
    v
Gateway cache
    |
    +-- Hit:
    |      return cached response
    |
    +-- Miss:
           call backend
           cache eligible response
           return response

Safe cache design must account for:

• HTTP method
• Hostname and path
• Query parameters
• API version
• Tenant scope
• Authorization context
• Language and content negotiation
• Freshness
• Invalidation

Gateway Timeouts

The gateway must use bounded timeouts.

Gateway timeouts should fit within the caller's complete request deadline.

Gateway Retries

The gateway can retry selected failures when the operation is safe to retry.

Gateway sends request to Backend A
      |
      v
Connection fails
      |
      v
Gateway evaluates retry policy
      |
      +-- Safe and within deadline:
      |      try another backend
      |
      +-- Unsafe or deadline exceeded:
             return controlled failure

A timeout or lost connection does not prove that the backend performed no work.

Idempotent Write Request

POST /api/enrollments HTTP/1.1
Host: api.example.com
Authorization: Bearer access-token
Idempotency-Key: unique-operation-key
Content-Type: application/json

{
  "courseId": 42
}

Gateway Security Controls

A gateway can provide defense-in-depth controls such as:

• TLS policy
• Mutual TLS
• Token validation
• Client-certificate validation
• Rate limits and quotas
• Request-size limits
• Method restrictions
• Header normalization
• Schema validation
• Web application firewall integration
• Private backend exposure
• Centralized security logging

The gateway does not replace secure service development. Each backend must continue enforcing authorization, validation, business invariants, and data protection.

Sensitive-data Handling

The gateway processes security-sensitive information such as:

• Access tokens
• API keys
• Session cookies
• Client certificates
• Tenant identifiers
• Request and response payloads

Avoid recording credentials, tokens, private headers, passwords, or complete sensitive bodies in ordinary gateway logs.

API Analytics

A gateway can collect consistent API-usage telemetry.

Useful measurements include:

• Requests by API and operation
• Requests by authenticated caller or subscription
• Successful and failed requests
• Gateway processing latency
• Backend latency
• Response-status distribution
• Rate-limit rejections
• Authentication failures
• Request and response size
• Cache hits and misses
• Retries and timeouts
• Traffic by API version

Structured Access Event

{
  "requestId": "request-correlation-id",
  "api": "course-api",
  "operation": "get-course",
  "apiVersion": "v2",
  "method": "GET",
  "status": 200,
  "gatewayDurationMs": 4,
  "backendDurationMs": 38
}

Distributed Tracing

Client
   |
   v
API Gateway
   |
   v
Course Service
   |
   +-- Cache
   +-- Database
   +-- Recommendation Service

A trace or correlation identifier helps connect gateway telemetry with backend logs and traces.

The gateway should preserve approved trace context and prevent untrusted callers from corrupting protected tracing fields.

Large Requests and Uploads

Large file uploads can be inefficient when the complete body passes through an API gateway.

Client
   |
   v
API Gateway
   |
   v
Upload Service
   |
   v
Object Storage

A direct-upload pattern can reduce gateway and application processing.

1. Client requests upload authorization.

2. API validates caller and file metadata.

3. API returns a short-lived authorized upload target.

4. Client uploads directly to object storage.

5. Application validates and finalizes the uploaded object.

The authorization, object key, size, content type, expiration, checksum, and finalization workflow must be controlled by the application.

WebSocket and Streaming APIs

Some gateways support WebSocket or streaming traffic, but connection behaviour differs from ordinary request-response APIs.

Review:

• Protocol support
• Maximum connection duration
• Idle timeouts
• Concurrent connection limits
• Message-size limits
• Authentication renewal
• Backend affinity
• Connection draining
• Client reconnection

Gateway High Availability

The gateway is on the critical request path and must not remain an unprotected single failure point.

Clients
   |
   v
One API Gateway
   |
   v
Many healthy services

Clients
   |
   v
Highly available entry point
   |
   +-- Gateway Instance 1
   +-- Gateway Instance 2
   +-- Gateway Instance 3
              |
              v
       Backend services

Gateway capacity, configuration, policies, certificates, identity-provider dependencies, and backend discovery must all be included in the availability design.

Gateway Scaling

The gateway tier can scale horizontally when instances are replaceable and configuration is distributed consistently.

Capacity planning should include:

• Requests per second
• Concurrent connections
• TLS handshakes
• Authentication-token validations
• Request and response sizes
• Transformation cost
• Aggregation fan-out
• Logging volume
• Cache memory
• WebSocket connections

Aggregation Fan-out

If each client request creates \(F\) backend requests, then a simplified backend-request estimate is:

\[ BackendRequestRate = ClientRequestRate \times FanOut \]

Example

Client requests:

2,000 requests per second


Backend calls per aggregated request:

4


Potential backend request rate:

2,000 × 4
=
8,000 backend requests per second

Retries and fallback calls can increase the actual backend rate further.

Avoiding a Gateway Monolith

A single gateway containing every route, transformation, business rule, and client-specific workflow can become difficult to modify and deploy.

One giant gateway

+-- Every public API
+-- Every partner API
+-- Every mobile operation
+-- Every web operation
+-- Business calculations
+-- Workflow coordination
+-- Data persistence

Possible boundaries include:

• Public API gateway
• Partner gateway
• Internal service gateway
• Mobile Backend for Frontend
• Web Backend for Frontend
• Administration gateway

Gateway boundaries should follow security, ownership, client, scaling, and operational requirements rather than being split arbitrarily.

API Gateway and Kubernetes

Internet
   |
   v
Cloud Load Balancer
   |
   v
API Gateway
   |
   v
Kubernetes Gateway or Ingress
   |
   +-- Account Service
   +-- Course Service
   +-- Enrollment Service
   +-- Search Service

The external API gateway can manage public API policy, while the cluster ingress or Gateway API implementation manages workload routing inside the platform.

Avoid duplicating the same authentication, rate limit, rewrite, retry, and timeout policy across several layers without a clear owner.

Conceptual API Policy

api:
  name: course-api
  version: v2
  path: /api/v2/courses/*

  security:
    authentication: required
    allowedAudiences:
      - learning-platform-api

  traffic:
    rateLimit:
      key: authenticated-caller
      policy: approved-api-policy

    requestBody:
      maximumSize: approved-limit

  backend:
    service: course-service
    timeout: approved-timeout
    retries:
      maximumAttempts: 1
      safeMethodsOnly: true

  observability:
    requestId: enabled
    metrics: enabled
    tracing: enabled

This example is conceptual. Apply the syntax and supported policies of the selected gateway platform.

PHP Trusted Gateway Example

<?php

declare(strict_types=1);

final class TrustedGatewayContext
{
    public function __construct(
        private array $trustedGatewayAddresses
    ) {
    }

    public function getTenantId(
        array $server
    ): int {
        $remoteAddress =
            (string)($server['REMOTE_ADDR'] ?? '');

        if (!in_array(
            $remoteAddress,
            $this->trustedGatewayAddresses,
            true
        )) {
            throw new RuntimeException(
                'The request did not come through a trusted gateway.'
            );
        }

        $tenantValue =
            (string)(
                $server['HTTP_X_TRUSTED_TENANT']
                ?? ''
            );

        if (!ctype_digit($tenantValue)) {
            throw new RuntimeException(
                'The trusted tenant context is missing.'
            );
        }

        return (int)$tenantValue;
    }
}

Production frameworks and identity libraries usually provide stronger mechanisms for trusted proxies, token validation, and claims handling. Prefer approved framework capabilities rather than custom security code.

Gateway Configuration Deployment

Prepare route and policy change
      |
      v
Validate configuration
      |
      v
Test security and routing
      |
      v
Deploy to controlled environment
      |
      v
Run smoke and contract tests
      |
      v
Deploy gradually
      |
      +-- Healthy:
      |      complete rollout
      |
      +-- Unhealthy:
             roll back

A gateway configuration error can affect several APIs simultaneously. Treat configuration as version-controlled, reviewed, tested, and observable production code.

Observability

Useful gateway metrics include:

• Requests by API and operation
• Successful and failed requests
• Gateway and backend latency
• Healthy backend count
• Authentication failures
• Authorization denials
• Rate-limit and quota rejections
• Request-validation failures
• Retry and timeout count
• Request and response sizes
• Cache hit rate
• Aggregation fan-out
• Active connections
• TLS handshake failures
• Traffic by API version
• Gateway CPU, memory, and network use

Alert Conditions

Alert when:

• Gateway availability falls below its objective
• Gateway or backend latency increases
• Backend error responses increase
• Healthy backend count falls below the required minimum
• Authentication failures rise unexpectedly
• Rate-limit rejection volume changes unexpectedly
• Gateway retries or timeouts increase
• One API operation dominates capacity
• TLS handshakes fail
• Configuration deployment fails
• Gateway capacity approaches a platform limit
• One API version receives unexpected traffic after migration

Troubleshooting Workflow

1. Capture the method, hostname, path, headers, and request ID.
2. Confirm DNS and TLS behaviour.
3. Identify the API and route selected by the gateway.
4. Check authentication and authorization policy results.
5. Check rate-limit, quota, and validation decisions.
6. Confirm the selected backend pool and healthy instances.
7. Check gateway-to-backend connectivity.
8. Check transformation and forwarding-header behaviour.
9. Check timeouts and retries.
10. For aggregation, inspect every backend dependency.
11. Compare gateway and backend logs using the request ID.
12. Inspect distributed traces.
13. Check whether the issue is version-specific.
14. Verify the latest gateway configuration deployment.

Common API-gateway Mistakes

Recommended Test Cases

API-gateway Best Practices

Practice Exercise

Design an API gateway for your online learning platform.

Requirements

1. Expose one HTTPS API endpoint.
2. Route course, account, enrollment, search, and payment APIs.
3. Validate access tokens for protected operations.
4. Forward approved identity and tenant context.
5. Prevent direct public access to backend services.
6. Apply separate rate limits for anonymous and authenticated callers.
7. Limit request-body and header sizes.
8. Expose API versions 1 and 2.
9. Create one mobile-friendly aggregated course-dashboard endpoint.
10. Keep payment and enrollment business rules in their backend services.
11. Define safe retry behaviour.
12. Use idempotency keys for enrollment submission.
13. Create gateway and backend timeout budgets.
14. Add request IDs and distributed tracing.
15. Protect sensitive values in logs.
16. Test backend and gateway failure.
17. Create a configuration rollback procedure.

API-gateway Design Template

Frequently Asked Questions