Software Development

MicroServices – Part 5 : Spring Cloud Zuul Proxy as API Gateway

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 application 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 microservice talking to APIs to get the relevant data. Instead of letting UI know about all our microservices details we can provide a unified proxy interface that will delegate the calls to various microservices based on URL pattern. In this post, we will learn how to create API Gateway using Spring Cloud Zuul Proxy.

MicroServices using Spring Boot & Spring Cloud

In this post we are going to learn:

  • Why do we need API Gateway?
  • Implementing API Gateway using Spring Cloud Zuul Proxy
  • Using Zuul Filters for cross-cutting concerns

Why do we need API Gateway?

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 API Gateway pattern in microservices architecture.


  • Provides easier interface to clients
  • Can be used to prevent exposing the internal microservices structure to clients
  • Allows to refactor microservices without forcing the clients to refactor consuming logic
  • Can centralize cross-cutting concerns like security, monitoring, rate limiting etc


  • It could become a single point of failure if proper measures are not taken to make it highly available
  • Knowledge of various microservice API may creep into API Gateway

Implementing API Gateway using Spring Cloud Zuul Proxy

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

Let us create a front-end UI module “shoppingcart-ui” as a SpringBoot 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;

public class ShoppingcartUiApplication {
    public static void main(String[] args) {, 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, ex: 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 UI is completely unaware of where is the actual catalog-service running, 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 zuul.prefix property.


Now from 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 is exposed through Zuul proxy but not inventory-service.

Using Zuul Filters for cross-cutting concerns

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 javax.servlet.http.HttpServletRequest;
import java.util.UUID;
import static;

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

Published on Java Code Geeks with permission by Siva Reddy, partner at our JCG program. See the original article here: MicroServices – Part 5 : Spring Cloud Zuul Proxy as API Gateway

Opinions expressed by Java Code Geeks contributors are their own.

Siva Reddy

Katamreddy Siva Prasad is a Senior Software Engineer working in E-Commerce domain. His areas of interest include Object Oriented Design, SOLID Design principles, RESTful WebServices and OpenSource softwares including Spring, MyBatis and Jenkins.
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

1 Comment
Newest Most Voted
Inline Feedbacks
View all comments
5 years ago

Very useful Siva… Thanks…

Back to top button