Anatomy of an API Gateway

Nowadays, the microservice architecture pattern is a hot term and it is a common solution in terms of designing and implementing enterprise, cloud based applications.

I have read a lot about microservice architecture pattern and I would like to collect and summarise what I have learned so far.

The following article takes a look at the API Gateway application and its roles and main actions in a microservice architecture application.


When it comes to developing an application based on the microservice architecture we have to take into consideration multiple requests coming from multiple clients, at same time!
An example of client is a web application, a mobile application or a third-party application.
Let’s say we have an online store application that uses the microservice architecture pattern and we have to expose a REST API service in order to allow different clients application to interact with customers's orders.

Our microservice architecture application has a service, called orderManager which is in charge of dealing with orders. However, there are also other microservices that serve different kind of data.For example,

  • Product Info Service - basic information about the product such as title, author
  • Pricing Service - product price
  • Order service — purchase history for product
  • Inventory service — product availability
  • Review service — customer reviews …

As a result, multiple requests must be sent among different microservices in order to return results to the client.

So, the big question is : How do the clients of a Microservices-based application access the individual services?

According to the expert,

The granularity of APIs provided by microservices is often different from what a client needs. Microservices typically provide fine-grained APIs, which means that clients need to interact with multiple services. For example, a client needing the details for a product needs to fetch data from numerous services 2

From a technical point of view, a client could make requests to each of the microservice directly.
In fact, each microservice has public API endpoints. However, this approach has some issues.
First of all, the fine-grained APIs exposed by each of the microservices could be very different and far from clients needs.
Using this approach,clients have to send several separate requests to multiple microservices in order to get the requested data. In more complex scenario, they might have to make an enormous number of requests.
Moreover, those multiple requests are to be sent over the public Internet and over a mobile network as well. It would probably result in a failure or in a bad user experience.
In addition, some microservices might use protocols that are not intended to be used outside of a LAN. For example, one might use the AMQP messaging protocol and another one might use RPC.
Therefore, this approach forces the client code to be much more complex and to deal with different protocols, while it should use protocols such as HTTP and WebSocket to interact with a backend application.

It goes without saying that this approach makes it difficult to refactor a microservice.
In fact, if we have to change a microservice or merge two services or split a service into two services we must take into account a refactoring of the clients functions.
In general, it rarely makes sense to implement this approach and let clients access directly the microservices APIs.
In addition, there are other issues to take into account.

  • Different clients need different data. For example, the desktop browser version of a product details page desktop is typically more elaborate then the mobile version.
  • Network performance is different for different types of clients. For example, a mobile network is typically much slower and has much higher latency than a non-mobile network. And, of course, any WAN is much slower than a LAN. This means that a native mobile client uses a network that has very difference performance characteristics than a LAN used by a server-side web application. The server-side web application can make multiple requests to backend services without impacting the user experience whereas a mobile client can only make a few.
  • The number of service instances and their locations (host+port) changes dynamically
  • Partitioning into services can change over time and should be hidden from clients2

A working solution is to use what is know as API Gateway

Definition of API Gateway

An API Gateway is a key element of the microservice architecture pattern.
It is a server that is the single entry point into our microservice architecture based application, from all clients.
All requests from clients go through the API Gateway which routes them to the appropriate microservice.
Therefore, it encapsulates the internal system architecture and expose a higher level API endpoints to address each clients requests.
According to the experts, the API Gateway pattern is similar to the Facade pattern from object-oriented design. In fact, a facade is an object that provides a simplified interface to a larger body of code, such as a class library.
The Facade design pattern is often used when a system is very complex and there are a large number of interdependent classes. It hides the complexities of a larger system and provide a simpler interface to the client which doesn’t need to know the internal implementations details.

Main responsibilities of an API Gateway

An API Gateway is responsible for

  • requesting routing
  • composition
  • protocol translation

It might have the following responsibilities

  • provide client with authentication (for example OAuth2 or JWT)
  • system monitoring
  • load balancing
  • requests caching
  • requests manipulation
  • static response handling

How an API Gateway handles requests

Some requests don’t need to be processed and they can be proxied/routed directly to the appropriate service
Some others requests need data that have to be collected form multiple microservices. Consequently, the API Gateway has to send multiple request to different microservices and collect/edit and then compose the response for the client. It goes without saying that an API Gateway could use protocol translation methods to supports different web and web-unfriendly protocols among internal microservices. It makes the whole translation process transparent to the client.

A variation of the API GATEWAY : The Backend for Front-End pattern

The API Gateway could provide a one size fits all API, but it will end up having a big layer of application dealing with all kind of clients. This leads to everything being thrown in together, and as a result, we will lose isolation of functionalities and we will experience issues trying to release them independently.

A variation of the API Gateway solution is a model that implements an API Gateway application to deal with one specific user interface or application. It is often referred to as backend for frontends (BFFs)1 3.
So, we can have an API Gateway for each client with a custom API backend. Usually a custom API backend is exposed for mobile clients.
From a team work point of view, this solution allows the team focusing on any given user interface or application to also handle its own server-side backends.

With this approach, if we need an API authentication and authorisation layer, this can be deployed between the BFF and the user interface or application.
It goes without saying that these BFFs applications should only contain functionalities specific to delivering a particular user request/experience.
So it’s important to not include business logic in the endpoints these BFF applications expose.The business logic should stay in the microservices themselves.
We can have an BFF application that expose just the public API endpoints to a third-party applications.

Benefits of an API Gateway

  • Hides the internal architecture of microservices
  • Insulates the clients from the problem of determining the locations of service instances
  • Provides the optimal API for each client
  • Reduces the number of requests/roundtrips. For example, the API gateway enables clients to retrieve data from multiple services with a single round-trip. Fewer requests also means less overhead and improves the user experience. An API gateway is essential for mobile applications.
  • Simplifies the client by moving logic for calling multiple services from the client to API gateway

Drawbacks of an API Gateway

An increasing of the complexity has to be take into consideration. In fact, an API Gateway is a service that must be developed, deployed and managed. Therefore, there is also a risk that an API Gateway becomes a development bottleneck. For this reason, the development of new
functionalities and the updating of an APIGateway must be as lightweight as possibile.

It is worthwhile to note that there is also an increment of the response time due to the additional network hop through the API Gateway.

How to handle partial Failures

If one service call another service that is either responding slowly or is not available, an API Gateway could hide that issue and returns a response to the waiting client, even if it is an error message.
Surely this kind of issues could be addressed in a different number of ways, depending of the specific scenario.
For example, with the help of a circuit-breaker pattern we can simply return an error if the data that have been requested from a client are taking a long time to be returned.

Depending of the implementations, the API Gateway could also return a cached version of the requested data. In fact the most recent data could be stored in an external databases such as Redis, and could be used to resolve a partial failure scenario.

From my point of view, A Queue system could be another options. Firstly we could submitted the failed request to a Queue system that will send it again until the appropriate service became available and will return a response.
Secondly, the API Gateway could respond with a cached version of the data or return an error due to an implementation of a circuit breaker pattern.

In conclusion, an API Gateway is an essential component of the microservice architecture pattern. It is responsible for request routing, composition, and protocol translation. It provides each of the application’s clients with a custom API. The API Gateway can also mask failures in the backend services by returning cached or default data.

External References: