API Gateway and Service Discovery in Spring Cloud

API Gateway and Service Discovery

As a system grows past a handful of services, two problems appear that individual services shouldn't have to solve on their own: how do external clients find the right service without knowing internal topology, and how do services find each other when instances scale up, scale down, and get rescheduled constantly? This guide covers the two building blocks that answer these questions in a Spring Cloud stack: the API Gateway for edge routing, and service discovery for internal service resolution — plus centralized configuration, which both depend on.

1. Why You Need an Edge Layer

Without a gateway, every client (web app, mobile app, third-party integrator) needs to know the address of every service, handle auth for each one individually, and adapt when service topology changes. An API Gateway centralizes this into a single, well-known entry point.

What a gateway centralizes

2. Spring Cloud Gateway: Routes, Predicates, Filters

Spring Cloud Gateway (built on Project Reactor/Netty) is Spring's non-blocking API gateway. Routing is defined declaratively as a set of routes, each combining a predicate (when to match) and filters (what to do to the request/response).

# application.yml
spring:
  cloud:
    gateway:
      routes:
        - id: order-service-route
          uri: lb://order-service          # lb:// = resolve via service discovery
          predicates:
            - Path=/api/orders/**
          filters:
            - StripPrefix=1
            - AddRequestHeader=X-Gateway-Source, edge
            - name: CircuitBreaker
              args:
                name: orderServiceCB
                fallbackUri: forward:/fallback/orders
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 50
                redis-rate-limiter.burstCapacity: 100
                key-resolver: "#{@userKeyResolver}"
 
        - id: payment-service-route
          uri: lb://payment-service
          predicates:
            - Path=/api/payments/**
            - Method=GET,POST
          filters:
            - StripPrefix=1
            - name: Retry
              args:
                retries: 2
                statuses: BAD_GATEWAY, GATEWAY_TIMEOUT
                methods: GET
 
        - id: legacy-user-service-route
          uri: http://legacy-user-service.internal:8080
          predicates:
            - Path=/api/users/**
            - Header=X-API-Version, v1
          filters:
            - StripPrefix=1
            - RewritePath=/api/users/(?<segment>.*), /legacy/users/${segment}

Programmatic route configuration (equivalent to YAML)

@Configuration
public class GatewayRoutesConfig {
 
    @Bean
    public RouteLocator customRoutes(RouteLocatorBuilder builder) {
        return builder.routes()
            .route("order-service-route", r -> r
                .path("/api/orders/**")
                .filters(f -> f
                    .stripPrefix(1)
                    .addRequestHeader("X-Gateway-Source", "edge")
                    .circuitBreaker(c -> c
                        .setName("orderServiceCB")
                        .setFallbackUri("forward:/fallback/orders")))
                .uri("lb://order-service"))
            .build();
    }
 
    @Bean
    public KeyResolver userKeyResolver() {
        // Rate-limit per authenticated user rather than globally
        return exchange -> Mono.justOrEmpty(
            exchange.getRequest().getHeaders().getFirst("X-User-Id")
        ).defaultIfEmpty("anonymous");
    }
}

Common gateway filters

3. Service Discovery: Client-Side vs Server-Side

Once you have more than one instance of a service (which you always do in production), something needs to track which instances are alive and where they are. This is service discovery, and it comes in two architectural flavors.

4. Eureka: Client-Side Discovery in Spring Cloud

Eureka is Netflix's service registry, integrated into Spring Cloud as Spring Cloud Netflix Eureka. Services register themselves on startup and send periodic heartbeats; other services query the registry to resolve instances.

Setting up a Eureka server

@SpringBootApplication
@EnableEurekaServer
public class DiscoveryServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(DiscoveryServerApplication.class, args);
    }
}

# discovery-server application.yml
server:
  port: 8761
 
eureka:
  client:
    # A standalone registry doesn't need to register with itself
    register-with-eureka: false
    fetch-registry: false
  server:
    # In dev, disable self-preservation so dead instances are evicted quickly
    enable-self-preservation: false

Registering a service as a Eureka client

# inventory-service application.yml
spring:
  application:
    name: inventory-service   # this is the logical name other services use to find it
 
eureka:
  client:
    service-url:
      defaultZone: http://discovery-server:8761/eureka/
  instance:
    prefer-ip-address: true
    lease-renewal-interval-in-seconds: 10
    lease-expiration-duration-in-seconds: 30

@SpringBootApplication
@EnableDiscoveryClient
public class InventoryServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(InventoryServiceApplication.class, args);
    }
}

5. Centralized Configuration with Config Server

As service count grows, keeping each service's application.yml in sync (database URLs, feature flags, rate limits) across environments becomes its own coordination problem. Spring Cloud Config Server centralizes configuration in a single Git repository (or Vault, or a database), served over HTTP to every service at startup — and optionally refreshed at runtime.

@SpringBootApplication
@EnableConfigServer
public class ConfigServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ConfigServerApplication.class, args);
    }
}

# config-server application.yml
server:
  port: 8888
 
spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/your-org/config-repo
          default-label: main
          search-paths: '{application}'
          clone-on-start: true

# inventory-service bootstrap.yml (or spring.config.import in Boot 3.x)
spring:
  config:
    import: "configserver:http://config-server:8888"
  application:
    name: inventory-service
  profiles:
    active: prod

// Beans annotated @RefreshScope pick up new values without a restart
// when POST /actuator/refresh is called (requires spring-boot-starter-actuator)
@RefreshScope
@Component
public class RateLimitProperties {
 
    @Value("${rate-limit.requests-per-second:100}")
    private int requestsPerSecond;
 
    public int getRequestsPerSecond() {
        return requestsPerSecond;
    }
}

6. Putting It Together: Request Flow Through the Stack

7. Choosing Your Discovery and Gateway Strategy

Key takeaways

• An API Gateway centralizes routing, auth, rate limiting, and TLS termination at the edge — but it should never contain business logic; that belongs in the owning service.
• Spring Cloud Gateway routes are predicate + filter pairs; lb://service-name routes through service discovery instead of a static address, decoupling the gateway from instance topology.
• Always strip client-supplied trust headers (e.g., X-User-Roles) at the gateway before setting your own — otherwise clients can forge them and bypass authorization.
• Client-side discovery (Eureka) resolves instances in the caller and calls directly, avoiding an extra hop; server-side discovery (k8s Service, service mesh) adds a hop but is language-agnostic and simpler for clients.
• Eureka's self-preservation mode is a deliberate safety feature against registry-side network partitions — don't "fix" it in production by disabling it, only in local/dev.
• On Kubernetes, prefer native Service discovery (and a mesh if you need mTLS/canary/traffic policy) over layering Eureka on top — it's redundant infrastructure solving an already-solved problem.
• Centralize configuration with Config Server backed by Git for audit history, but decouple config changes from deployments using @RefreshScope and /actuator/refresh.
• Never commit secrets to a config repository, even a private one — Git history is permanent. Use Vault or your orchestrator's secret store.

Interview Questions

• What problems does an API Gateway solve that individual services shouldn't solve on their own?
• Why should business logic never live inside gateway filters?
• Explain the difference between client-side and server-side service discovery, with examples of each.
• How does Eureka's heartbeat and lease-expiration mechanism work? What happens when a service instance stops sending heartbeats?
• What is Eureka's self-preservation mode, and why does disabling it in production carry risk?
• Walk through what lb://service-name does in a Spring Cloud Gateway route definition.
• How would you prevent a client from forging an internal trust header like X-User-Roles through the gateway?
• Why might you skip Eureka entirely on a Kubernetes deployment?
• What is the purpose of Spring Cloud Config Server, and how does it differ from just committing application.yml per service?
• How do you propagate a configuration change to running services without a full redeploy?
• Why should secrets never be stored directly in a config Git repository?
• Describe the full request path from an external client to a downstream service through a gateway, discovery server, and two internal services.
• What's the trade-off of adding a service mesh proxy on every hop versus direct client-side discovery calls?
• How would you implement rate limiting per authenticated user (not globally) at the gateway layer?