Microservices - Part 5: Spring Cloud Zuul Proxy as API Gateway

DZone 's Guide to

Microservices - Part 5: Spring Cloud Zuul Proxy as API Gateway

In this tutorial, we'll learn how to use Spring Cloud Zuul Proxy as an API gateway, an essential component of microservice architecture.

Free Resource

In microservices architecture, there could be a number of API services and few UI components that are talking to APIs. As of now, many microservices based applications still use monolithic front-ends where the entire UI is built as a single module. You may choose to go with micro-frontends where the UI is also decomposed into multiple microservices talking to APIs to get the relevant data. Instead of letting the UI know about all our microservices details, we can provide a unified proxy interface that will delegate the calls to various microservices based on a URL pattern. In this post, we will learn how to create an API Gateway using Spring Cloud Zuul Proxy.

In this post we are going to learn:
  • Why do we need an API Gateway?
  • Implementing an API Gateway using Spring Cloud Zuul Proxy
  • Using Zuul Filters for cross-cutting concerns

An API Gateway, aka Edge Service, provides a unified interface for a set of microservices so that clients no need to know about all the details of microservices internals. However, there are some pros and cons of using the API Gateway pattern in microservices architecture.

  • Provides an easier interface to clients.
  • Can be used to prevent exposing the internal microservices structure to clients.
  • Allows refactoring of microservices without forcing the clients to refactor the consuming logic.
  • Can centralize cross-cutting concerns like security, monitoring, rate limiting, etc.
  • It could become a single point of failure if the proper measures are not taken to make it highly available.
  • Knowledge of various microservice APIs may creep into the API Gateway.

Spring Cloud provides Zuul proxy, similar to Nginx, that can be used to create the API Gateway.

Let us create a front-end UI module "shoppingcart-ui" as a Spring Boot application which also acts as Zuul proxy. Create a SpringBoot project with Web, Config Client, Eureka Discovery, Zuul starters and annotate the main entry-point class with @EnableZuulProxy.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.zuul.EnableZuulProxy;

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

As we are using Eureka Discovery; also, requests from the proxy with the URL patterns /service-id/** will be routed to the service registered in Eureka Server with service id "service-id."

For example, from UI application if we make a request to http://localhost:8080/ catalog-service/products then it will lookup in Service Registry for ServiceID "catalog-service" and send the request with URL /products to one of the available catalog-service instances.

To make it happen we need to register "shoppingcart-ui" with Eureka Service Registry.


With this configuration now we can fetch product information from catalog-service using jQuery as follows:

    url: '/catalog-service/products'
.done(function(data) {
    this.products = data;

Here, from our UI application, we are making a call to http://localhost:8080/catalog-service/products. Assuming catalog-service is registered with ServiceID "catalog-service" and running on port 8181, this request will be forwarded to http://host:8181/products. But the UI is completely unaware of where the actual catalog-service is running and its hostname, port number, etc.

We can also use a common prefix for URLs, like "/api," for which we want Zuul to proxy by setting the zuul.prefix property.


Now, from the UI, we can make a request to fetch products at http://localhost:8080/api/catalog-service/products. By default, Zuul will strip the prefix and forward the request.

You can also customize the path mappings of a service as follows:


With this configuration, you can use URL http://localhost:8080/api/catalog/products which will be forwarded to the service with serviceId catalog-service.

By default, all the services registered with Eureka Server will be exposed. You can use zuul.ignored-services property to disable this behavior and expose only the explicitly configured services.




With this configuration, only catalog-service, order-service are exposed through Zuul proxy but not inventory-service.

As Zuul act as a proxy to all our microservices, we can use Zuul service to implement some cross-cutting concerns like security, rate limiting, etc. One common use case is forwarding the Authentication headers to all the downstream services.

Typically in microservices, we will use OAuth service for authentication and authorization. Once the client is authenticated OAuth service will generate a token which should be included in the requests making to other microservices so that client need not be authenticated for every service separately. We can use Zuul filter to implement features like this.

import com.netflix.zuul.ZuulFilter;
import com.netflix.zuul.context.RequestContext;
import com.netflix.zuul.exception.ZuulException;
import javax.servlet.http.HttpServletRequest;
import java.util.UUID;
import static org.springframework.cloud.netflix.zuul.filters.support.FilterConstants.PRE_TYPE;

public class AuthHeaderFilter extends ZuulFilter {
    public String filterType() {
        return PRE_TYPE;

    public int filterOrder() {
        return 0;

    public boolean shouldFilter() {
        return true;

    public Object run() throws ZuulException {
        RequestContext ctx = RequestContext.getCurrentContext();
        HttpServletRequest request = ctx.getRequest();

        if (request.getAttribute("AUTH_HEADER") == null) {
            //generate or get AUTH_TOKEN, ex from Spring Session repository
            String sessionId = UUID.randomUUID().toString();

            ctx.addZuulRequestHeader("AUTH_HEADER", sessionId);
        return null;

We are adding AUTH_HEADER as a request header using RequestContext.addZuulRequestHeader() which will be forwarded to downstream services. We need to register it as a Spring bean.

AuthHeaderFilter authHeaderFilter() {
    return new AuthHeaderFilter();

You can find the source code for this article at https://github.com/sivaprasadreddy/spring-boot-microservices-series.

api gateway ,zuul ,spring cloud ,microservices ,tutorial

Published at DZone with permission of Siva Prasad Reddy Katamreddy , DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}