Configuring API Gateway Architecture

Course: Advanced Java Training

Topic: Configuring API Gateway Architecture Using Spring Boot and Spring Cloud Gateway

Course Link: Advanced Java Training at JustAcademy

Demo Link: Register for a Course Demo

JustAcademy Website: Visit JustAcademy

1. Introduction to API Gateway Architecture

An API Gateway is a server-side component that acts as a single entry point for clients accessing multiple backend services. Instead of requiring a client application to communicate directly with every microservice, the client sends requests to the gateway, which routes them to the appropriate service.

In a Spring Boot microservices application, an API Gateway can simplify client communication, centralize selected cross-cutting concerns, and provide a consistent approach to request routing, security integration, monitoring, and resilience.

Spring Cloud Gateway is a gateway solution in the Spring ecosystem. It supports route definitions, request matching through predicates, request and response modification through filters, and integrations for features such as circuit breakers and rate limiting. Read the official Spring Cloud Gateway overview.

Example Scenario

Consider an e-commerce application with the following services:

• Product Service: Manages product information and catalog data.
• Order Service: Creates and manages customer orders.
• Payment Service: Handles payment processing and transaction status.
• User Service: Manages user profiles and related information.
• API Gateway: Receives client requests and forwards them to the correct backend service.

Without a gateway, a frontend application may need to know the address of every service. With a gateway, it can communicate through a common entry point.

2. Why Is an API Gateway Needed?

As a microservices system grows, clients may need to interact with many independently deployed services. Each service may have its own URL, security requirements, request limits, and error behavior. An API Gateway can provide a centralized location for managing common aspects of these interactions.

Main Benefits

• Single entry point: Clients use a common endpoint rather than maintaining a list of internal service addresses.
• Request routing: Incoming requests are directed to the appropriate backend service.
• Security integration: Authentication and selected authorization checks can be performed at the gateway, while backend services retain responsibility for protecting their own resources.
• Request filtering: Headers, paths, and responses can be modified according to defined rules.
• Rate limiting: Traffic can be restricted to protect services from excessive requests.
• Observability: Centralized request logging and metrics can improve visibility into incoming traffic.
• Resilience: Suitable filters and integrations can support timeouts, circuit breakers, and controlled fallback behavior.
• Client simplification: Clients do not need to understand every internal service boundary.

Limitations to Consider

• The gateway can become a bottleneck if it lacks sufficient capacity.
• A single gateway instance can become a single point of failure if it is not deployed redundantly.
• Excessive business logic in the gateway makes it harder to maintain.
• Every gateway hop introduces some latency.
• Centralized security configuration must be managed carefully to avoid exposing protected services.

3. How API Gateway Architecture Works

The gateway receives a client request, evaluates configured routes, executes applicable filters, forwards the request to a backend service, and returns the backend response to the client.

Client Application
        |
        v
   API Gateway
        |
        +----------------------+
        |          |           |
        v          v           v
 Product       Order        Payment
 Service       Service       Service
        |          |           |
        v          v           v
 Product DB    Order DB     Payment DB

Request Processing Flow

1. The client sends an HTTP request to the gateway endpoint.
2. The gateway evaluates route predicates to identify a matching route.
3. Applicable global and route-specific filters process the request.
4. The gateway forwards the request to the configured backend service.
5. The backend service executes its business logic and produces a response.
6. The gateway applies any applicable response processing.
7. The gateway returns the response to the client.

Spring Cloud Gateway uses route definitions, predicates, and filters to determine where requests go and how they are processed. Filter logic can run before or after the downstream request. Explore the Spring Cloud Gateway reference documentation.

4. Important API Gateway Components

5. Setting Up a Spring Cloud Gateway Project

Spring Cloud Gateway can be used to build a dedicated gateway application. For the WebFlux implementation, the project uses Spring Boot, Spring WebFlux, and Project Reactor. The gateway dependencies must be compatible with the chosen Spring Boot version and Spring Cloud release train.

Step 1: Create the Project

Create a new Spring Boot project using Spring Initializr or your preferred development environment. Select the gateway dependency that matches the implementation you intend to use.

Common dependencies for a WebFlux-based gateway include:

• Spring Cloud Gateway Server WebFlux.
• Spring Boot Actuator for operational monitoring, when required.
• Spring Security for gateway-level security integration, when required.
• A compatible Spring Cloud LoadBalancer or service discovery integration if dynamic service resolution is needed.
• Testing dependencies for route and integration tests.

Use the Spring Cloud release train compatible with your Spring Boot version. Avoid combining arbitrary versions of Spring Boot and Spring Cloud.

Step 2: Create the Main Application Class

package com.example.apigateway;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class ApiGatewayApplication {

    public static void main(String[] args) {
        SpringApplication.run(
            ApiGatewayApplication.class, args
        );
    }
}

The @SpringBootApplication annotation enables Spring Boot configuration and component scanning. The application starts the gateway runtime when the appropriate gateway and web dependencies are present.

6. Configuring Routes in application.yml

Routes determine which backend service receives a matching request. Spring Cloud Gateway supports route configuration through properties and programmatic configuration.

Example Route Configuration

server:
  port: 8080

spring:
  application:
    name: api-gateway
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: product-service-route
              uri: http://localhost:8081
              predicates:
                - Path=/api/products/**
              filters:
                - StripPrefix=1

            - id: order-service-route
              uri: http://localhost:8082
              predicates:
                - Path=/api/orders/**
              filters:
                - StripPrefix=1

            - id: user-service-route
              uri: http://localhost:8083
              predicates:
                - Path=/api/users/**
              filters:
                - StripPrefix=1

Configuration note: This example uses the property structure for current Spring Cloud Gateway Server WebFlux releases that expose configuration under spring.cloud.gateway.server.webflux. Some earlier Spring Cloud Gateway versions use spring.cloud.gateway.routes. Follow the reference documentation for the exact version in your project.

Understanding the Configuration

• server.port sets the port on which the gateway listens.
• spring.application.name gives the gateway application a name.
• id identifies a route uniquely within the gateway configuration.
• uri specifies the destination service address.
• predicates specify the conditions required for route matching.
• filters specify request or response processing for a matched route.
• StripPrefix=1 removes the first path segment before forwarding the request.

Example of StripPrefix

If a client sends GET /api/products/25, the route matches /api/products/**. With StripPrefix=1, the gateway removes the first segment, api, and forwards the request path as /products/25.

The backend service must therefore expose an endpoint compatible with the rewritten path. If the Product Service expects /api/products/25, remove the filter or configure the path transformation to match the service contract.

7. Understanding Route Predicates

A route predicate determines whether an incoming request satisfies a condition for a route. Multiple predicates configured on a route are generally combined so that the request must satisfy the route's configured conditions.

Common Route Predicates

Example: Route by HTTP Method

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: product-read-route
              uri: http://localhost:8081
              predicates:
                - Path=/api/products/**
                - Method=GET

This route matches GET requests under /api/products/**. Other HTTP methods will not match this route unless another route handles them.

8. Configuring Gateway Filters

Gateway filters can modify incoming requests, process downstream responses, or implement cross-cutting behavior. Spring Cloud Gateway provides built-in filters for common tasks, while custom filters can be created for application-specific requirements.

Common Built-in Filters

Example: Add a Request Header

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: product-route
              uri: http://localhost:8081
              predicates:
                - Path=/api/products/**
              filters:
                - AddRequestHeader=X-Gateway-Source, api-gateway

The gateway adds the X-Gateway-Source header to the downstream request. Treat custom headers as informational unless they are securely controlled. Do not trust client-supplied identity headers as proof of authentication.

Applying Default Filters

Default filters are useful when the same supported filter must apply to every configured route. The precise property path depends on the Spring Cloud Gateway version.

spring:
  cloud:
    gateway:
      server:
        webflux:
          default-filters:
            - AddResponseHeader=X-Gateway, enabled

This example adds a response header to responses processed by configured routes. Confirm the property path and filter syntax against the version-specific documentation before using it in a project.

9. Implementing a Route Programmatically

Routes can also be created in Java using a RouteLocator bean and RouteLocatorBuilder. This approach is useful when route definitions need programmatic construction.

package com.example.apigateway.config;

import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.route.builder.RouteLocatorBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class GatewayRouteConfig {

    @Bean
    public RouteLocator customRoutes(
            RouteLocatorBuilder builder) {

        return builder.routes()
            .route("product-service-route", route -> route
                .path("/products/**")
                .uri("http://localhost:8081"))
            .route("order-service-route", route -> route
                .path("/orders/**")
                .uri("http://localhost:8082"))
            .build();
    }
}

This example demonstrates programmatic routing. It assumes that the backend services accept the paths as forwarded. If the public path differs from the backend path, add an appropriate path transformation filter. Keep route definitions in one configuration approach unless there is a clear reason to combine approaches.

10. Integrating Service Discovery

In a small local environment, backend services may use fixed URLs. In a larger deployment, service instances can change as containers restart, replicas scale, or workloads move between hosts. Service discovery allows the gateway to resolve a service by a registered logical name.

Using a Logical Service URI

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: product-service-route
              uri: lb://PRODUCT-SERVICE
              predicates:
                - Path=/api/products/**

The lb:// scheme indicates load-balanced service resolution. This configuration requires a compatible Spring Cloud LoadBalancer integration and a service discovery or service-instance source capable of resolving PRODUCT-SERVICE. The logical name must match the registered service ID and configured naming rules.

Benefits of Service Discovery

• Reduces dependence on hardcoded service-instance addresses.
• Supports scaling to multiple service instances.
• Allows service locations to change without updating every route manually.
• Can work with a registry such as Eureka or Consul when the appropriate integration is configured.

Service discovery does not automatically guarantee that every instance is healthy. Health checking, load-balancing configuration, deployment readiness, and failure handling must also be considered.

11. Configuring Load Balancing

Load balancing distributes incoming requests across multiple instances of a backend service. When the gateway uses service discovery and a compatible load-balancing integration, a logical service URI can be resolved to an available instance.

Example

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: order-route
              uri: lb://ORDER-SERVICE
              predicates:
                - Path=/api/orders/**

When multiple Order Service instances are registered and discoverable, the load-balancer integration can select an instance for a request.

Load-Balancing Best Practices

• Run enough service instances to meet availability and capacity requirements.
• Configure readiness and health checks at the deployment level.
• Monitor instance failures and request latency.
• Set appropriate connection and response timeouts.
• Test behavior when one or all backend instances become unavailable.

12. Securing the API Gateway

The gateway is often exposed to external clients, making it an important security boundary. It can enforce common authentication requirements and apply request-level protections. However, gateway security should not be the only protection for sensitive backend operations.

Important Security Measures

• Use HTTPS for client-to-gateway communication and secure internal traffic where appropriate.
• Integrate an established authentication mechanism, such as OAuth 2.0 or OpenID Connect.
• Validate access tokens and their issuer, audience, expiry, and required scopes.
• Apply rate limits and request-size limits to reduce abuse.
• Restrict access to internal services so they cannot be called directly by unauthorized clients.
• Remove or overwrite untrusted headers that could be mistaken for trusted identity information.
• Keep credentials and signing keys outside source code.
• Protect management endpoints and avoid exposing sensitive diagnostic information.
• Log security events without recording access tokens or sensitive personal data.

Authentication vs. Authorization

A gateway may authenticate a request and enforce broad access policies, but the Order Service should still verify that the authenticated user is allowed to view or modify the specific order requested.

13. Rate Limiting and Traffic Protection

Rate limiting restricts how many requests a client or identity can make within a defined period. It helps protect backend services from accidental overload and abusive traffic.

Common Rate-Limiting Strategies

• Per-IP limiting: Restricts requests from a client IP address or network identity.
• Per-user limiting: Applies limits based on an authenticated user identity.
• Per-client limiting: Applies limits to a registered application or API consumer.
• Per-route limiting: Applies stricter limits to sensitive or expensive endpoints.

Spring Cloud Gateway supports a Redis-based request rate limiter in compatible configurations. Using it requires the corresponding Redis integration, appropriate configuration, and a reliable Redis deployment.

Rate-Limiting Considerations

• Choose limits based on expected traffic and backend capacity.
• Define how clients should handle throttling responses, commonly HTTP 429.
• Use a trusted identity key for per-user or per-client limits.
• Account for proxy headers carefully when identifying client IP addresses.
• Monitor rejected requests and adjust limits using real traffic data.

14. Circuit Breakers and Resilience

A circuit breaker helps prevent repeated calls to a failing downstream service from consuming excessive resources. It can temporarily stop calls and allow the system to recover. Spring Cloud Gateway supports circuit-breaker integration through compatible Spring Cloud CircuitBreaker implementations.

How a Circuit Breaker Works

1. Closed state: Requests are allowed to reach the backend.
2. Open state: Calls are rejected or redirected after the failure threshold is reached.
3. Half-open state: A limited number of test calls determine whether the backend has recovered.

Resilience Best Practices

• Configure connection and response timeouts.
• Use bounded retries only for suitable failures.
• Avoid retrying non-idempotent operations without an idempotency strategy.
• Use circuit breakers for important downstream dependencies where appropriate.
• Define safe fallback responses only when they make business sense.
• Monitor failure rates, circuit state changes, and downstream latency.

A fallback should not report a successful payment or order when the actual operation failed. It should communicate an appropriate status, such as temporary unavailability, or return cached data only when that behavior is valid for the endpoint.

15. Handling Errors and HTTP Status Codes

A gateway should return clear and consistent error responses. Errors can originate from route matching, gateway filters, authentication, rate limiting, network failures, or backend services.

The exact status code depends on the failure and configured behavior. Do not expose internal stack traces, infrastructure details, or confidential backend information in client-facing error messages.

16. Logging, Monitoring, and Distributed Tracing

In a microservices architecture, a single request may pass through the gateway and several backend services. Observability helps teams understand the request path and identify where failures or delays occur.

Logging

• Record request method, route identifier, response status, and processing duration where appropriate.
• Use a correlation ID or trace ID to connect related log entries.
• Mask tokens, passwords, and sensitive request data.
• Use structured logging for easier filtering and analysis.

Metrics

Monitor request volume, latency percentiles, error rates, active connections, rate-limit rejections, and downstream failures. Use metrics to distinguish a gateway performance issue from a backend service problem.

Distributed Tracing

Distributed tracing records the path of a request across services. OpenTelemetry-compatible instrumentation and a tracing backend can help identify slow downstream calls and dependency bottlenecks.

Health Checks

Spring Boot Actuator can provide health and application metrics endpoints when configured. Expose only the endpoints required by monitoring infrastructure and protect operational endpoints from unauthorized access.

17. API Gateway Testing Strategy

Gateway testing should validate route matching, filters, security behavior, failure handling, and the interaction between the gateway and downstream services.

Testing Checklist

• Test valid and invalid paths.
• Test every configured route and HTTP method.
• Verify rewritten paths against backend controller mappings.
• Confirm that sensitive headers are handled safely.
• Test backend unavailability and slow responses.
• Verify that error responses do not reveal internal details.
• Measure gateway performance under realistic traffic.

18. Common API Gateway Configuration Problems

19. Practical Project: Build an API Gateway for an E-Commerce System

Objective: Create a Spring Cloud Gateway application that routes client requests to independent Product, Order, and User services.

Project Requirements

1. Create a gateway application on port 8080.
2. Create or reuse a Product Service on port 8081.
3. Create or reuse an Order Service on port 8082.
4. Create or reuse a User Service on port 8083.
5. Configure routes for product, order, and user endpoints.
6. Use route predicates to match the correct paths and methods.
7. Apply path transformations only when needed by the backend contracts.
8. Configure authentication and authorization according to the application's requirements.
9. Add appropriate timeouts, error handling, and rate limits.
10. Add health monitoring, structured logging, and correlation identifiers.
11. Write automated tests for route behavior and backend failures.

Example Public API Design

Expected Learning Outcomes

• Understand how clients access multiple backend services through a gateway.
• Configure and test route predicates and filters.
• Recognize the role of service discovery and load balancing.
• Apply appropriate gateway security and traffic controls.
• Diagnose common routing and downstream connectivity errors.
• Understand how observability improves production support.

20. Interview Questions and Answers

Q1. What is an API Gateway?

Answer: An API Gateway is a single entry point that receives client requests and forwards them to appropriate backend services. It can also handle common concerns such as authentication integration, filtering, rate limiting, and monitoring.

Q2. What is Spring Cloud Gateway?

Answer: Spring Cloud Gateway is a Spring ecosystem project for routing API requests and applying cross-cutting concerns through route predicates and filters.

Q3. What is a route in Spring Cloud Gateway?

Answer: A route defines a destination URI, a route identifier, matching predicates, and optional filters that process matching requests and responses.

Q4. What is a route predicate?

Answer: A predicate determines whether a request matches a route. Predicates can match request attributes such as path, HTTP method, host, headers, query parameters, or time.

Q5. What is the purpose of a gateway filter?

Answer: A gateway filter modifies or processes a request or response. Examples include adding headers, rewriting paths, removing headers, and applying configured resilience behavior.

Q6. What is the difference between a gateway filter and a global filter?

Answer: A route-specific gateway filter applies to the route on which it is configured. A global filter provides behavior across routes when it is registered and applicable to the request processing pipeline.

Q7. What does StripPrefix do?

Answer: It removes a specified number of path segments before forwarding the request. For example, removing one segment from /api/products/5 produces /products/5.

Q8. What is the purpose of service discovery?

Answer: Service discovery helps applications locate service instances dynamically instead of relying entirely on hardcoded instance addresses.

Q9. How does load balancing work with an API Gateway?

Answer: When a compatible load-balancing integration is configured, the gateway can route requests addressed to a logical service name to one of the available service instances.

Q10. Why is rate limiting important?

Answer: Rate limiting restricts excessive traffic, helps protect backend capacity, and can reduce the impact of abusive or accidental request spikes.

Q11. How can a gateway handle a backend service failure?

Answer: It can use timeouts, controlled retries, circuit breakers, and suitable fallback behavior. The exact response should reflect the business operation and failure type.

Q12. Should all authorization logic be implemented in the gateway?

Answer: No. The gateway can enforce common access policies, but backend services should validate authorization for sensitive resources and business operations they own.

Q13. What is the difference between a gateway and a load balancer?

Answer: A load balancer distributes traffic among service instances. An API Gateway can route requests based on API paths and other request attributes and may also provide filtering, security integration, rate limiting, and observability. The responsibilities can overlap depending on the infrastructure.

Q14. How do you troubleshoot a 404 error at the gateway?

Answer: Verify that the incoming request matches a configured route, inspect path predicates, check filter order and path rewriting, and confirm that the resulting backend path exists.

Q15. What is the difference between a gateway and a service registry?

Answer: The gateway receives and routes client requests. A service registry stores or exposes information about service instances so compatible clients or gateways can discover them.

21. Best Practices for API Gateway Architecture

• Keep gateway logic focused on routing and cross-cutting concerns rather than business workflows.
• Use stable and meaningful route identifiers.
• Keep public API contracts consistent and documented.
• Use the Spring Boot and Spring Cloud versions supported by the selected release train.
• Protect backend services from direct unauthorized access.
• Configure timeouts and avoid unbounded retries.
• Use rate limiting based on trusted client or user identity where appropriate.
• Deploy multiple gateway instances when availability requirements demand it.
• Monitor route errors, request latency, downstream failures, and resource consumption.
• Keep secrets out of configuration files committed to source control.
• Test route matching, filters, security, and failure scenarios automatically.
• Document routing rules and maintain a controlled process for changing them.

22. Quick Revision Checklist

• Understand the purpose of an API Gateway.
• Know the difference between routes, predicates, and filters.
• Configure Spring Cloud Gateway routes in YAML or Java.
• Understand path rewriting and prefix removal.
• Recognize when service discovery and load balancing are required.
• Apply authentication, authorization, and secure header handling.
• Understand rate limiting, timeouts, and circuit breakers.
• Return appropriate errors without exposing internal details.
• Use logs, metrics, tracing, and health checks for observability.
• Test gateway behavior with valid requests, invalid requests, and failed backends.
• Verify all configuration properties against the exact framework version.

23. Conclusion

Configuring API Gateway Architecture is an important step in building maintainable Spring Boot microservices applications. The gateway provides a controlled entry point for client traffic and routes requests to the appropriate backend services using predicates and filters.

A reliable design combines clear route definitions with appropriate security, service discovery, load balancing, rate limiting, resilience, monitoring, and automated testing. The gateway should simplify communication without becoming a repository for business logic or a single point of failure.

Begin with a small set of routes, verify the public and backend path contracts, and gradually introduce additional capabilities as the application requires them.

24. Learning Resources

• Advanced Java Training at JustAcademy
• Register for a Course Demo at JustAcademy
• Visit the JustAcademy Website
• Spring Cloud Gateway Official Project Page
• Spring Cloud Gateway Reference Documentation
• Spring Guide: Building a Gateway