Microservices External API Integration Patterns

6 min readSep 25, 2022

This is the 7th post in a series on microservices architecture. This article is originally published at https://www.learncsdesign.com

Designing an application’s external API is made even more challenging by the diversity of its clients. These clients typically have different data requirements.

Direct Communication

It is possible to design APIs in such a way that clients can directly invoke the services. Microservice architecture rarely employs this approach due to the following drawbacks.

Clients must make multiple requests to retrieve the data they need with fine-grained service APIs, which is inefficient and can result in a poor user experience.
Due to the lack of encapsulation caused by clients knowing about each service and its API, it is difficult to change the architecture and APIs.
Clients might not find it convenient or practical to use IPC mechanisms used by services.

Maintaining long-term backward compatibility cannot be left to the developers of the backend services. Organizations should develop a separate public API instead of exposing services directly to third parties.

This is accomplished through an architectural component known as an API gateway.

API Gateway Pattern

Direct access to services has numerous drawbacks. An API gateway would be a far better approach.

Basically, an API gateway is a service that acts as an entry point to the application from the outside. This component is responsible for request routing, API composition, and other cross-cutting concerns such as authentication, monitoring, and rate-limiting. API gateways are similar to the facade design pattern in OOPS. An API gateway encapsulates the internal architecture of an application and provides an API to its clients.

API gateways are also responsible for request routing, API composition, and protocol translation. API requests from external clients go through an API gateway, which routes some requests to the appropriate service. API gateways handle other requests by invoking multiple services and aggregating the results. The server may also translate between client-friendly protocols such as HTTP and WebSockets and client-unfriendly protocols used by the services.

Request Routing

Request routing is one of the most important functions of an API gateway. API gateways implement API operations by routing requests to the appropriate services. The API gateway consults a routing map to determine which service to route a request to when it receives a request. A routing map might map, for example, an HTTP method and path to the HTTP URL of service. Web servers such as NGINX provide reverse proxying as part of this function.

API Composition

API gateways typically do more than just reverse proxying. They may also perform API operations using API composition. API gateways provide clients with a coarse-grained API that enables them to retrieve the data they need with just one request.

The Aggregator/Composition pattern has two subpatterns.

Chained Pattern — Basically, this type of composition pattern follows a chain structure. In this pattern, the client communicates with the service, and all the services are chained together so that the output of one service becomes an input of the next.
Branch Pattern — The branch pattern is an extended version of the aggregator and chain patterns. The client can directly communicate with the service, and the service can communicate with more than one service simultaneously in this design pattern.

Protocol Translation

API gateways may also translate protocols. Although the application services use a variety of protocols internally, including REST and gRPC, it might provide a REST API to external clients. Several API operations are translated between the RESTful external API and the internal gRPC-based APIs when needed.

Backends for Frontends Pattern

An API gateway could provide a single one-size-fits-all API. One of the problems with a single API is that different clients often have different requirements. The solution to this problem is to give clients the option of specifying in a request which fields and related objects the server should return like with GraphQL. For a public API that must serve a broad range of third-party applications, this approach is adequate, but it does not provide clients with the control they require.

Providing clients with their own APIs through the API gateway is a better approach.

Implementing Cross-Cutting concerns

API gateways primarily handle API routing and composition, but they may also handle cross-cutting concerns. Examples of cross-cutting concerns include:

Authentication — Verifying the identity of the client making the request.
Authorization — Verifying that the client is authorized to perform that particular operation.
Rate limiting — Limiting how many requests per second from either a specific client or all clients.
Caching — Cache responses to reduce the number of requests made to the services.
Metrics collection — Collect metrics on API usage for billing analytics purposes.
Request logging — Log requests.

API Gateway Architecture

API gateways have a layered, modular architecture. It consists of two layers, the API layer, and the common layer. One or more API modules make up the API layer. API modules implement APIs based on client requirements.

Benefits of API Gateway

The main advantage of using an API gateway is that it encapsulates the internal structure of the application.
API gateways provide clients with client-specific APIs, reducing the number of round-trips between the client and the application
It also simplifies the client code.

Drawbacks of API Gateway

It is yet another highly available component to develop, deploy, and manage.
It is possible that the API gateway becomes a development bottleneck since developers must update the API gateway to expose their services API.

Off-the-shelf API gateway

There are several off-the-shelf services and products that implement API Gateway features.

AWS API Gateway — An AWS API Gateway API is a set of REST resources, each of which supports one or more HTTP methods. You can configure the API gateway to route each request to a backend service. You would need to implement API composition in the backend services because it doesn’t support API composition.

Kong — Kong is based on the NGINX HTTP server, which allows you to define flexible routing rules based on HTTP method, headers, and path to decide which backend service to use.

Developing API Gateway

With the web framework, you can build your own API gateway that proxies requests to other services. Let’s take a look at Netflix Zuul and Spring Cloud Gateway.

Netflix Zuul — Zuul is a Netflix framework that implements cross-cutting functions such as routing, rate limiting, and authentication. Zuul uses the concept of filters, which are reusable request interceptors similar to servlet filters. Zuul handles an HTTP request by assembling a chain of filters that transform the request, invoke backend services, and transform the response before it’s sent to the client.

Spring Cloud Gateway — Spring Cloud Gateway is an API gateway framework based on Spring Framework, Spring Boot, and Spring Webflux, a reactive web framework.

The Spring Cloud Gateway provides a simple yet comprehensive way to accomplish the following: 