Why Do API Gateways Exist?

The first API gateways I noticed appeared in 2006. At that time, SOAP web services were still very new, and those messages could get very complex. XML schema validation, XML encryption, XML signatures, SOAP envelopes, SOAP headers and SOAP body, XML namespaces, WSDL, WSS, XSL, XPath—all of these technologies appeared in a relatively short period of time. And all of them had to be mastered in order to support a web service infrastructure.

To access the value status, XPath is required. The expression looks like this:

/soapenv:Envelope/soapenv:Body/soapenv:Fault/detail/gw:policyResult/@status

That is quite a selector for such a short message! It is not easy to build by anyone who is new to XML-related technologies. For this purpose, some API gateways provide easy-to-use graphical interfaces that allow users to create this XPath expression by simply selecting the element based on an example message.

Unfortunately, wherever it was required to expose business interfaces as SOAP web services, developers needed to support these technologies in all of their APIs. This required specific knowledge and had potential for mistakes, especially when it came to encryption, digital signatures, and SAML. From a business logic point of view, having to support these technologies was considered overhead since they were not really part of the API feature itself.

Similar to mobile applications today, there is always the effort of implementing the foundation of the app. Components that handle security, authentication, authorization, session management, all of that is not really the app, but still required. To help mobile developers, SDKs are available to take care of many of these technologies.

For SOAP web services, products have been made available to help API developers, similar to mobile SDKs to help app developers. The first products I worked with were the Layer 7 SecureSpan SOA Gateway (later the CA API Gateway)² and IBM DataPower.³ The main goal was to take the burden off of developers by supporting all these XML-based technologies in an easily accessible way. Developers could then concentrate on their API business logic and let the API gateways handle all the complicated, non-business API logic separately.

A typical scenario, which I have worked on myself, was the following.

A medical report would be sent to the health insurance company. The report would be signed and partially encrypted. In addition, the report would be sent via TLS with client authentication.

The API gateway would validate the SSL session, the digital signature, would check for rate limits and messages size, and it would do XML schema validation. It would take care of validating the complete message. Decrypting the message would be an option, depending on the use case. Developers of backend business APIs could now expect to handle validated messages only! For example, the signature validation would not be necessary since it was already done!

Nowadays these SOAP web services may still be running but new SOAP web services rarely appear. Instead, RESTful API interfaces have taken over. Although message structures may not be as complex anymore, the need for introspection still exists. The complex message structure has been replaced by having to support multiple parameters including optional ones, explicit HTTP method validations, and different types of payloads. Requirements such as rate limits and message size validations have not changed. In addition, new protocols such as OAuth and OpenID Connect have been created and need to be handled, too.

What Are API Gateways Used For?

It is a long list and it’s not even complete. Other categories can be found, but they are more like “you can but you should not necessarily do this or that using an API gateway.” As mentioned, on a high level it is all about externalizing non-business, API-related features in the API gateway. What that means in detail is described best by an example.

Let’s say a business API has to validate and persist incoming paystubs. The requests must be sent by authorized clients who are identified by an OAuth access_token. The API must apply validations to assure reliability and security. Once the request has been validated, the API must associate the given paystub with a user and persist it. All actions must be logged for historical and compliance reasons.

I visualize it as shown in Figure 7-2.

The percentage may not match in all cases, but it is roughly what I have seen in real-life scenarios. The point is, everything that is not part of the core feature of an API is part of its infrastructure. If you multiply this by the number of APIs, it can be imagined that many resources are used only to get to a point where the business implementation can be started.

The goal of having an API gateway is to externalize these tasks. With an API gateway, those 9 requirements can be implemented in front of the business API, done by a different developer team. And, even if it is the same team, the API gateway provides features that support the developers to get ahead fast. The API gateway not only speeds up implementations, it also eases the operation of services! Internal standards can be applied, logging can be aligned, and API protection can be aligned—all of this due to having one single component that “sees” all traffic.

After all, the business API only receives requests that have been validated. This also reduces the required processing power for them. Figure 7-3 displays this.

The API gateway takes care of most requirements and filters incoming requests to only forward valid messages to the backend. Steps 1 and 2 on the backend side are additional required steps. They are to assure that requests were received by the API proxy and that the user is the one associated with the paystub. After that, the backend can handle its paystub feature.

If you now ask why the user can’t be authorized by the API proxy, the answer is quite simple: API gateways should not implement business-relevant validations! Only the business API itself should do that. Otherwise, a lot of context needs to be made available to the API gateway and that raises privacy concerns and potential replication challenges.

In many cases, the requirements in front of different business APIs will be the same, or at least similar. Knowing this opens the door for tremendous simplifications. Ideally it becomes so simple that a developer could be placed in front of a website and simply fill out a dialog with check boxes and input fields. A click on a “Deploy service” button will create a new API on the API proxy and all these requirements will be implemented. Simple as that!

I would like to share a prototype that I have worked on. This is the scenario.

A backend API is exposed via an API gateway. The API gateway must filter the incoming request, forward it to a backend, and inspect responses. If the responses are valid, they are returned to the requesting client. The web UI of the prototype looks similar to the one shown in Figure 7-4.

Each box represents a piece of required configuration for creating an API: the external URL (https://external), filter (RateLimit, Content-Type check), the backend URL (https://internal) that implements the business logic, and the response inspection (content inspection of the backend response) back to the requesting client. The web UI includes a few dialogs (Figure 7-5) that enable a developer to provide required values.

At the end a “Deploy service” button generates a deployment descriptor that goes into a version control system and is used to generate code for different API proxy target systems. Since the code for the API proxy is generated, no errors are possible. Each API follows best practices, include error handling and generating comments so that readers of the implementation will know what it does.

It is hopefully obvious that anyone could fill out these dialogs. No hardcore technology knowledge is needed. The best part about all of this is the fact that none of this influences the business API. It can be developed without knowing anything about the API proxy implementation. The contract between those two would be an API definition such as the Swagger document discussed previously.

Mocking APIs

I would like to share one of those use cases that are not always obvious. API gateways are great to “mock” services. If a client must be built to consume a backend API that has not yet been realized, testing tools can be used. However, another alternative is to use the API gateway that will later expose the proxy API. Until the backend API is completed, the proxy API can be built to take incoming requests and return success and error responses. Where Figure 7-5 shows a dialog to configure the backend API URL, it can simply be set to something like http://localhost/fake. The implementation would do nothing else than return a HTTP status 200, fake response message. This also speeds up the whole development process. To give an impression how easy this can be, Figure 7-6 displays a screenshot of such a fake API, implemented on CA API gateway.

A client passes in an HTTP header (line number 3) named x-testcase, which sets a variable named testcase. Further down the API takes the appropriate action. For a success message, it will return what is shown in the lower right dialog.

Many cases can be handled. It can also be done based on other incoming parameters or request payloads. Ideally the API gateway will require request messages and return responses that also match the Swagger API definition. With that, only the content would be fake, but message formats and structures could already be verified!

Another powerful feature is the capability of simulating failing backend systems, added latency, connection breakdowns—all the cases no one would like to see in a production system, but still need to handle!

Why Is It Important to Leverage API Gateways?

All these reasons enable different teams to work on features at the same time, each one on its own component. Let’s have a closer look into each one.

Decoupling

Figure 7-7 gives an idea how attributes in regard to decoupling could be implemented and/ or supported.

The API gateway is located within the DMZ and receives requests from external clients. The requests include an OAuth access_token and a JSON payload. The API gateway will validate the access_token and retrieve the associated username. In addition, it will inspect the payload. Depending on that, it is able to evaluate which backend API of which version should handle this message (this is also called content-based routing). Since the backend API requires an XML payload, the API gateway transforms the JSON payload into that.

The API gateway creates a request for the target backend API and includes the username as an HTTP header in addition to the XML payload. The load balancer in between the API gateway and the backend APIs serves one IP address, which resolves to the matching backend API by examining the requests URL path. Each target backend receives and processes the request that matches exactly their interface.

This setup provides the flexibility for the backend API developers to develop and test new versions whenever they feel like it. Once the backend API is ready for production, the load balancer can be updated to route to the new backend API if required. Lastly, the API gateways logic to inspect the payload gets updated. That enables it to include the new backend API as a target location. The API gateway can also be prepared earlier in the development process but either ignores requests that are received with a newer payload or simply forwards them to an older version. Many possibilities appear once this setup has been established.

Integration and Scaling

Integration is a strong argument for the existence of API gateways. As an architect, I work with customers who have questions regarding this topic often! Typical integrations include custom IDPs (Active Directory, Oracle Access Manager, CA SSO, Open LDAP), different databases (MySQL, Oracle, Cassandra), FTP servers, email servers, mobile notifications—almost anything that is available. Even integrations with mainframes! Figure 7-8 gives an overview.

The beauty is that API gateways already support the technology to integrate with each of these systems. They only require configurations (exceptions exist). The backend API developer does not need to include a single line of code to support these integrations. Having these possibilities enables new use cases also. A request could be received via an email, checked for viruses using ICAP, and afterwards forwarded to a backend API. If this had to be handled by the backend itself, it could require skill sets that may not exist in teams.

Note

Because of these integration capabilities, API gateways are sometimes also referred to as lightweight ESBs.⁴ ESBs receive a request and processes it through many different channels until the message is finally sent to the main recipient.

Scaling is another big and important topic. Scaling may be required to serve a higher load from the external network but sometimes also into the internal network. A combination of both is certainly also possible. However, scaling is nothing that can be handled by any component itself. The network topology must be prepared for it. Adding a new API gateway or backend API is not an easy task and requires the correct setup beforehand. Needless to say, this is something that is necessary, no matter what component has to be scaled.

If the backend needs scaling, it can be done independently of the API gateway. Session stickiness between the API gateway and a particular backend API may be required but that can be handled. Scaling in that direction can also include rate limiting per backend API. The exposed API on the gateway can be configured to prevent the backend API from failing or getting overloaded.

Caching is also an interesting capability. Often, APIs return the same result, for example, configurations. In those cases, an API gateway could cache these types of responses for a specified amount of time to reduce the overall load to backend services and the overall latency.

In the other direction, looking into the external network, the API gateway itself may need to scale. In that case, it needs to be located behind a load balancer itself, and more nodes can be included. If scaling has not been a topic for anyone reading this section, Figure 7-9 illustrates what it means.

Figure 7-9 contains multiple API gateways and backend APIs. It should illustrate the idea that components are created based on demand. Since they are all interconnected with each other in one way or the other, a well-planned strategy for scaling is required. A client will always send requests to the same address, but this request may be handled by different servers. This scenario needs to be supported! Having stateless components with no sessions is helpful but not always possible.

Having unique feature sets and playing such a vital role, API gateways are also great for auditing and logging. If all requests are processed by an API gateway, the API gateway is able to log and audit all messages if desired! This comes at a cost of decreased performance, but it may be valid for some environments. Turning on and off auditing and logging for certain time frames or during escalations is also possible.

Let’s consider a case where employees use an enterprise app. However, this app sometimes fails for some users. In addition, due to their roles, the app may access an API on backend XXX and sometimes on backend ZZZ. If logging only exists on the backend APIs, it could be challenging to discover what is going wrong. Having the API gateway in-between allows logging of usernames, request times, target backend APIs, backend API response errors, latency between APIs—all in a central location no matter what the target API may be.

If you feel that logging and auditing causes concerns in regard to privacy or access control nightmares, there is good news. API gateways (at least some) include role-based access. It is possible to limit who can do what and who can see what based on user roles or other attributes. This not only includes access to log files or audits; this also includes access to deployed APIs. This can also be used to simplify the case where API gateways are shared between different teams. Depending on team membership, these developers may only have access to reading API implementations or audits or configurations. Fine granular controls are available and should be leveraged.

API Gateway Alternatives

As an architect who has worked with API gateways since 2006, I usually say, There is no alternative. You need to have it! Needless to say, this is too easy as an acceptable answer. Of course alternatives exist!

A drawback of not having a dedicated component to handle incoming and outgoing traffic is the distribution of data. It is very difficult to apply company-wide, or at least business unit-wide, guidelines for securing and auditing APIs. Different teams have to be convinced of the usefulness and encouraged to follow these guidelines. Even small things like auditing become challenging since most teams have their own rules for auditing what, when, and how. If teams feel that adhering to these guidelines requires extra effort, they will ignore them as long as possible!

Nevertheless, I have seen one example where customers built a well-working system themselves. It was built from the ground up. The reason for its success was the fact that a team was formed and treated as a product development team. Requirements were collected, the scope of the project was well defined, timelines were specified, and releases were made available often to collect feedback from other employees. In addition, the system was well documented.

Summary

API gateways (API proxies) play a vital role in any environment that exposes RESTful APIs. API gateways are located so that all incoming and outgoing traffic can be inspected by them. Applying security rules, implementing logging requirements, enabling reviewers—all of this is supported. The burden of implementing non-functional requirements in regard to a business API is taken of the developers’ plates. Each team can concentrate on its own strengths. Alternatives do exist, but they often end up being a maintenance nightmare and difficult to manage.