API Gateway Architecture and Design

1. Why Do We Need an API Gateway?

An application may start with one backend. The frontend communicates with one server, and that server handles authentication, requests and business logic.

When the backend is split into services, direct access becomes harder to manage. The client may need to know where each service runs, which service handles each operation and what changes when a service moves.

Several services may also repeat the same technical work:

• Validating authentication tokens
• Checking broad access permissions
• Applying request limits
• Creating request IDs
• Recording access information
• Handling technical errors

An API gateway provides one controlled entry point in front of these backend services. The client sends requests to the gateway, which applies the relevant rules and forwards each request to its destination.

What is an API Gateway?

An API gateway is a server between API clients and backend services. It receives a request, applies entry-point policies, forwards it to the appropriate service and returns the response.

For the client, the gateway acts as the API server. For the backend service, it acts as the caller.

The Three Main Jobs

Routing chooses the destination. Proxying performs the exchange.

Forward Proxy and Reverse Proxy

• A forward proxy acts on behalf of clients when they contact servers.
• A reverse proxy acts on behalf of servers when clients contact them.

An API gateway performs reverse proxying and adds API-specific policies around it.

2. What Belongs in the Gateway?

The gateway handles technical entry rules. Backend services remain responsible for business rules.

For example, the gateway can require an administrator role for a protected operation. The target service must still check whether that administrator is allowed to modify a particular resource.

Moving resource ownership checks and domain logic into the gateway would couple it to every backend service. Over time, it would become another large application that must change whenever business rules change.

The gateway controls entry. The target service validates the business operation.

Related Components

3. What Are We Building?

GateKeeper is a backend-focused API gateway and API management platform built with Spring Boot, direct HTTP communication, Redis and Kafka.

The project demonstrates how gateway responsibilities work internally. It is an educational implementation with a defined scope, rather than a replacement for a mature production gateway.

Main Applications

Small Catalog and Order demo services will act as targets behind the gateway. Their purpose is to demonstrate forwarding and policies; they are not separate, full-sized business projects.

Planned Capabilities

Dynamic Routing

Dynamic routing means that routes are stored as configuration instead of being hard-coded into a large conditional block.

A route describes information such as its destination, allowed methods, authentication requirements, permitted roles, request limit, timeout and active status.

The Management Service stores these settings in MySQL. The Gateway loads active routes into memory and uses them for route matching. Updating a route does not require changing and rebuilding the Gateway's source code.

4. Data Plane and Control Plane

Separating live traffic from configuration management is a central design decision.

The data plane needs a short, predictable request path. The control plane handles administration and durable configuration storage.

Once the Gateway has loaded its routes, it can continue using that configuration during a temporary Management Service outage. New configuration loads and updates depend on the Management Service becoming available again.

5. Why Build a Custom Gateway?

Using an API gateway is common and useful. Building a complete production gateway from scratch is a much larger commitment.

A production gateway may need high concurrency, connection pooling, streaming, multiple protocols, certificate management, service discovery, load balancing, resilience mechanisms, monitoring and ongoing security maintenance.

GateKeeper focuses on a smaller set of responsibilities so the underlying design is easier to understand. It brings together Spring Security, filters, interceptors, HTTP communication, Redis, Kafka, database ownership, exception handling and AOP in one project.

Features Outside This Project's Scope

• Spring Cloud Gateway, Eureka and Spring Cloud Config
• Service discovery and load balancing
• Circuit breakers and automatic retries
• General response caching
• Request or response body transformation
• XML-to-JSON conversion
• WebSocket, gRPC and GraphQL proxying
• File uploads and streaming proxy support
• TLS termination
• API keys, billing and quota products
• Business-process orchestration

These features can be useful in other systems. They are excluded here to keep the project focused and manageable.

In particular, automatic retries can add delay and duplicate writes. Redis is used for rate limits and idempotency, not general caching of backend responses.

6. How the Design Controls Latency

A gateway adds an extra network hop and processing work. It cannot provide zero additional latency.

GateKeeper keeps that extra work limited by avoiding unnecessary synchronous dependencies.

If the Gateway contacted separate authentication, routing, logging and analytics services for every request, each call would add time and another possible point of failure.

Instead, GateKeeper keeps routing and token validation local. Redis is consulted for policies that require shared state. The target service is then contacted over HTTP.

Local JWT Validation

The Management Service will authenticate users and issue signed JWTs. The Gateway will validate those tokens locally rather than calling the Management Service for every protected request.

This removes a recurring network call. It also means the Gateway is not fetching current user information on every request. Token expiry, key rotation and revocation are separate concerns; full revocation is outside this project's scope.

Routes in Memory

MySQL remains the durable source of route configuration. The Gateway's in-memory registry is the copy used for fast request processing.

Routes are loaded at startup and refreshed when configuration changes. The Gateway does not read MySQL directly.

7. Redis: Immediate Shared State

Redis is a fast key-value data store. GateKeeper uses it for short-lived state needed while deciding whether a request can continue.

Why Not Use Only Java Memory?

Memory belongs to one running process. If multiple Gateway instances maintained separate counters, each instance would see only the requests it received.

Redis provides shared state that those instances can consult. Even with one Gateway running locally, this demonstrates the reason for separating shared runtime state from process memory.

Key Concepts

Atomicity matters when requests arrive together. Separate reads and writes can allow two requests to act on the same old value. A Redis Lua script can group related counter and expiry operations into one atomic operation.

Rate Limiting

Rate limiting restricts how many requests a user or client may make to a route within a time window.

Redis holds the counter. The Gateway updates it atomically, checks the configured limit and rejects requests that exceed it. Expiration removes counters after their useful window.

POST Idempotency

Idempotency handling helps avoid repeating an operation when a client resends the same request.

For configured routes, Redis will hold temporary processing state and a saved successful response associated with an idempotency key. A matching completed request can receive the saved response without forwarding the operation again.

This is different from general response caching. It is tied to identifying a repeated operation.

Redis Boundaries

Redis does not hold the authoritative route configuration or analytics history. MySQL and MongoDB have those responsibilities.

8. Kafka: Asynchronous Events

Kafka is a durable event-streaming platform. A producer writes an event to a topic, and a consumer reads it independently.

The consumer does not need to process the event immediately. Kafka retains records according to its configured retention, allowing consumers to process them later.

Key Terms

Access Events

The Gateway publishes request outcome metadata to gateway-access-events. The Analytics Service consumes these events and stores them in MongoDB.

Useful metadata includes the event ID, correlation ID, route, request method, outcome, duration and whether a rate-limit rejection or idempotency replay occurred.

Passwords, JWTs, cookies and authorization headers must not be included in access events.

Configuration Events

The Management Service publishes route-change notifications to gateway-configuration-events.

A notification identifies what changed. The Gateway then fetches the latest configuration from the Management Service and refreshes its in-memory registry.

The event is a notification; MySQL remains the source of truth through the Management Service.

Duplicate Events

A consumer may receive an event again during failure recovery. The Analytics Service will use a unique eventId to avoid storing the same access event twice.

A correlationId serves a different purpose: it links work associated with one incoming request. An eventId identifies one event for deduplication.

Redis and Kafka Serve Different Needs

The Gateway does not wait for Analytics or MongoDB to finish processing an event. Publishing still has a cost, and producer failures need handling; an asynchronous send alone does not guarantee that events can never be lost.

9. Service Responsibilities and Ownership

Smart Gateway Service

The public entry point and data plane.

Responsibilities:

• Route matching
• Correlation IDs
• JWT validation
• Role checks
• Rate limiting
• Idempotency
• Path and header rules
• Forwarding
• Timeouts
• Gateway errors
• Access-event publication

Ownership:

• Holds active routes in memory
• Uses Redis for temporary policy state
• Loads configuration through the Management Service
• Contacts target services over HTTP
• Has no MySQL or MongoDB database
• Owns no business-domain tables

API Management Service

The control plane for users, routes and policies.

Responsibilities:

• Manage credentials and roles
• Issue JWTs
• Store route configuration
• Maintain configuration versions
• Publish change notifications
• Audit administrative actions (via AOP)

Ownership:

• Owns MySQL data for:
  • Users
  • Roles
  • Routes
  • Policy settings
  • Versions
  • Audit records
• Other services must not directly modify its tables.

Analytics Service

Processes Gateway access events into operational information.

Responsibilities:

• Consume events
• Deduplicate events
• Store event documents
• Support statistics such as:
  • Request counts
  • Outcomes
  • Average duration
  • Slow routes
  • Rate-limit rejections
  • Idempotency replays

Ownership:

• Owns MongoDB data for:
  • Access events
  • Processed-event records
• Does not change route configuration
• Does not participate in forwarding live requests

Catalog and Order Demo Services

Small downstream services used to demonstrate:

• Routing
• Authorization
• Path rewriting
• Header propagation
• Timeouts
• Duplicate request handling

Their business logic stays deliberately small. They remain responsible for their own business-level validation and authorization.

Infrastructure Ownership

10. Complete Architecture

The architecture separates live traffic, configuration management and analytics.

Live Request Path

The client contacts the Gateway. The Gateway uses local route and security information, consults Redis when a configured policy needs it, and forwards permitted traffic to the target service. The target's response returns through the Gateway.

Management, MySQL, Analytics and MongoDB are not contacted for every forwarded request.

Configuration Path

An administrator changes configuration through the Management Service. That service saves the change in MySQL and publishes a Kafka notification. The Gateway fetches the latest configuration and updates its local registry.

This path runs during startup and configuration refresh, not for every client request.

Analytics Path

The Gateway publishes an access event to Kafka. The Analytics Service consumes it and stores the information in MongoDB. The client does not wait for this processing to complete.

Architectural Boundaries

• Only the Smart Gateway forwards live target API traffic.
• The Gateway accesses route configuration through Management, not through MySQL.
• The Gateway does not call Analytics or MongoDB during forwarding.
• Analytics does not administer routes.
• Each service controls its own persistent data.
• Target services retain business-specific security checks.

11. What Happens When a Component Fails?

Fail closed means refusing a request when a required policy cannot be checked, rather than silently bypassing the policy.

Separation reduces unnecessary dependencies. It does not make the system immune to failures: a component required for the current request can still affect that request.

12. Initial Setup and Health Check

The first implementation milestone uses three Spring Boot applications:

• smart-gateway-service
• api-management-service
• analytics-service

Each application should start independently, use a distinct port and answer a simple health-check request.

The health check confirms that the application can start and respond over HTTP. It does not, by itself, prove that Redis, Kafka, MySQL, MongoDB or the complete gateway workflow is ready.

Quick Revision

Key Takeaways

1. An API gateway provides a single entry point for client requests to backend services.
2. The data plane (Gateway) handles live traffic; the control plane (Management) defines rules.
3. Routes are stored in MySQL but loaded into Gateway memory for fast matching.
4. JWT validation happens locally to avoid authentication service calls on every request.
5. Redis provides shared state for rate limiting and idempotency across Gateway instances.
6. Kafka enables asynchronous event delivery for access logging and configuration updates.
7. Each service owns its own data: Management owns MySQL, Analytics owns MongoDB.
8. The Gateway does not contact Management, Analytics or databases during forwarding.
9. Business logic remains in target services; the Gateway handles technical entry policies.
10. The architecture balances latency, reliability and separation of concerns.