API Gateway and Its Nuances

This post discusses a few nuanced points of an API Gateway for connecting to backend services and micro-services from clients such as browsers or external applications. First, let us visit common features and design of an API gateway.

If you are building software using microservices or modernizing SOA, you are either planning or providing API to your services. An API Gateway maps external urls (end-point) to internal urls, provides security layer, instrumentation and audit log capabilities. Since the services may be elastic, their hosts/ IP addresses can change. In order to make clients transparent of such changes, an API Gateway also uses discovery service or DNS. To recap, an API Gateway is an abstraction layer which provides following functionalities:

1. Mapping external requests’ URL: It maps external URLs to internal URLs using a table, service discovery service, DNS etc.
2. Security: It enforces security such as CSRF, XSS, access control, authorization, IP whitelist / blacklist enforcement, detection of anomalies v/s historical usage patterns.
3. Building logs of interactions with client for audit and troubleshooting.
4. API metering: Meters API requests, permit or deny request based on threshold limits.
5. Analytics: Creates a logs of timing, rate, failure etc. for analytics purpose.
6. API tracing: This is discussed below in detail.
7. Documentation: API Gateway can also serve documentation and examples of API.

API Gateway design and functionality are well understood therefore, in this post, we will focus on its nuances. The following is a list of a few nuanced points.

1. Long term service discovery needs: API gateway should be able to discover services using different mechanism. Some services may be external with well known URLs and ip-addresses, others may be dynamic in nature. In a multi-cloud environment, service discovery needs may vary.
2. API Trace: Since API Gateway is the first point of interaction with the client, it can tag each request with a unique tracking id. If down-stream services use this tag in log messages and also propagate it while calling other services, it can be used to trace the API call end-to-end. This is very useful for debugging, troubleshooting, audit and analytics.
3. API Orchestrator: API Gateway should be generic. Any custom code should be avoided in it. But there are use-cases when it is needed that the server abstracts a number of API calls into one. Such abstraction may be needed for simplicity, performance etc. reasons. Such a functionality should be provided by a special service called API Orchestrator.

Let us examine the design of an API Gateway using the following diagram.

API Gateway and Its Cooperating Components

The above diagram is self explanatory. Its components are well understood. We can skip over well-understood components and focus on the ones emphasized in this post.

Service Discovery and End Point Mapper

URL mapping is simple in concept, match incoming URL pattern on outgoing URL pattern. But in practice it gets interesting when you consider, services move from one machine to another, one zone to another, one cloud to another, there are failure — entire zone may fail etc.

API Gateway can map an incoming URL using following steps:

1. Use a static table to match the URL with a service name.
2. If service name is IP-address or URL with hostname in it then it is the destination URL.
3. If the service name is not URL, another entry in the table can give the name of discovery-service. Use interface to the corresponding discovery-service to get the IP address of destination service. These are a few commonly used discovery-services.

a. Consul

b. Netflix Ribbon

c. DNS

d. Custom DIscovery Services

End-point mapper makes it easy to adapt to new environment.

API Orchestration

API orchestration services are special type of light services that takes an API call, split in into multiple API calls, aggregate result of each and return back the aggregation as the result of the original request. API orchestration is required to simplify client API, improve performance and security. A few example of security are, masking value of certain attributes, enforcing a filter to remove sensitive data or enforcements of client roles etc. An API orchestration service should follow these principles:

1. It should be data driven based on the incoming request and metadata deployed with it. For example, an incoming Graph QL can be mapped to API call using meta-data. It is a template-service (service that can acquire personality based on supplied templates).
2. It should support plugins using scripts. These plugins can be used for imperative logic. A request can be mapped to appropriate plugins using meta-data. Based on the platform support they can be serverless function-as-a-service (FaaS) such as AWS Lambda. Or depending on the language they can code written in JavaScript, Groovy, Java or C# etc.

API Tracing

I leant that API tracing is very useful for debugging, troubleshooting and performance metering during development. They can also be used in audit logs and analytics. The concept is simple, when a API invocation hits the gateway, insert a unique UUID in HTTP header (X-TRACE-ID / TRACE-ID/ TRACKING-ID). In downstream services, when you log any message also log trace-id. The parameters of incoming request are normally available in one way or another (depending on the language). For example, in Java it could be made available by injection, thread local.

You can also build analytics / monitoring tool / search based on tracking id. You can also show log messages for particular trace-id from different services side by side. By adding time, user session info (which user) you can make it very useful trouble shooting / debugging tool. Now if a user comes and tells you, around 12:20 PM when I tried such and such thing, it failed, you know what to do.

API Gateway Options

We conclude article by providing a list of a few API Gateway software.

1. Kong: https://getkong.org/
2. Spring Cloud based on Netflix Zuul: http://projects.spring.io/spring-cloud/
3. Netflix Zuul: https://github.com/Netflix/zuul
4. Open Source Trillo API Gateway (disclaimer, I am an author of Trillo): This is based on Spring Cloud and Netflix Zuul (a data driven wrapper around it): https://github.com/trillo/trillo-server
5. Amazon API Gateway: https://aws.amazon.com/api-gateway/
6. WSO2 API Manager: http://wso2.com/products/api-manager/