API Gateway or the code way

"Listen to me, coppertop. We don't have time for twenty questions. Right now, there is only one rule. Our way… or the highway."

Ring a bell? That look on Neo's face, hoping Trinity would save the day… About to get out of the car like "fine, I'll walk," then Trinity steps in and he stays. Hard to believe it's been 25 years. Great movie — worth a rewatch.

What's the connection? With API Gateway, the situation is similar: "API Gateway or the code way." With two differences: nobody's pulling a gun, and we do have time for questions.

In this article we'll try to answer "What is an API Gateway good for?", "Why use one?", "Should we use one?" in a way that someone new to Web Service development can follow.

A quick note before we start: don't get stuck on the literal meaning of "API." The context here is Web Services used as APIs. When people say "Web Service" they often think SOAP, WSDL, XML; when they say "API" they think REST, OpenAPI, JSON. We'll use both terms more or less interchangeably.

Get yourself a Web Service

Let's start by writing a sample Web Service. The language and protocol don't matter — an API Gateway can be used for all Web Services regardless of language or protocol. Follow any quickstart and in a few minutes you'll have a working service.

So what's the problem?

"Okay, I wrote and ran the service in five minutes. How hard can it be to add a few more methods?" Sound familiar?

Developing a Web Service isn't that big a deal. You might say "real-world services aren't this simple" — and often they're not that complex either. Much of the time we're just making things we already do in-house — database work, algorithms, existing app logic — callable over the network. That's the essence of a Web Service: making a method callable over HTTP.

The real difficulty starts when the number of services and clients grows quickly. Here are some examples:

1. Authentication. You usually don't want everyone calling your services. You need some form of authentication so only defined users can access them.
2. Authorization. As the number of users and methods grows, you get requests like "these people can call these methods but those people can't." You need authorization.
3. IP restriction. You may need to accept requests only from certain IPs, or reject from others. Ask the network team to update firewall rules every time? Friction.
4. Content filtering. Are all incoming requests benign? There may be attacks. How will you block them? Rely on the network team again?
5. Encryption / decryption. "I exposed the service over HTTPS, what else do you need?" doesn't always fly. Some clients insist on payload encryption. You might even get "sign requests, verify signatures, sign responses."
6. WS-Security. There's a standard for that whole encrypt-decrypt- sign-verify dance, used in some SOAP environments. Good luck to anyone writing a client for it.
7. Schema validation. If you expect a certain message structure — "integer in this field, date in that one" — don't you need to enforce that?
8. Scheduled availability. "My service should only run on these weekdays, these hours; the rest of the time it should be down." How would you handle that?
9. Message transformation. As the number of clients grows, you get more requests like "change the message structure," "omit null fields," "send arrays like this." Sometimes you have to do it.
10. Redaction (client-specific responses). Your service returns a fixed structure, but later: "return this extra field to this user type but hide it from others." Then you either duplicate services or write code that returns different responses per client.
11. Logging. Always required. "Who called?", "when?", "what did they send?", "what did we return?", "who did we send this data to?" Keeping logs isn't enough — you need to query them.
12. Monitoring. You've built a service that must be up 24/7. How do you check it's up and responding correctly? If it stops, errors, or slows down, how will you know? Will you wait for complaint calls?
13. Error message handling. What error code in each situation? How do you customize them? "Do we need that? Can't we just return 500 with 'an error occurred'?" No. You have many clients and messages must be meaningful.
14. Maintenance. Ever tried to update a system while it's running? Now imagine that for your Web Service.
15. Moving the service. You may need to change the service address. If you have many clients, what then?
16. Load balancing and failover. As services become critical, you want to deploy on more servers and form a cluster. How do you do that?
17. Service governance. As the number of services grows, even tracking what exists becomes a problem. Which service was opened when, under which agreement, until when valid.
18. Documentation. How to use the services must be documented. How many engineers who have developed Web Services have prepared at least one OpenAPI file?

There are more, but these are enough. If you've read through and paused to think "how would I do all this?", you've seen how much work there is beyond coding the business logic. Some of it can be done in code; but you might have 100, 200, or 500 Web Services — how many people on your team can write code at that level, and how much of that code will need to be maintained? Step away from the urge to solve everything with code.

What is an API Gateway good for?

An API Gateway is the common name for software that handles the tasks above — and many more — without touching your Web Service code, through configuration. It sits in front of your Web Services, and their message traffic passes through it. That makes it possible to control, transform, or customize those messages in any way you need.

The client's request is received by a Proxy on the API Gateway. The Proxy is the proxy entity created on the gateway for the target Web Service; the client actually talks to the Proxy. The Proxy acts as a client to the Web Service, receives the response, and returns it to the client. Configuration on the Gateway customizes the Proxy's behavior, so security, traffic management, message transformation, service relocation, and similar needs can be managed from a single place.

Besides being low-latency, high-performance, and scalable, an API Gateway should offer easy-to-use interfaces, be deployable without becoming a Single Point of Failure, and support many users in different roles. Depending on your needs, the ability to integrate with or provide various tools and software also matters.

The obvious benefits of doing all this through configuration:

1. Web service development is reduced to coding business logic. Everything else is configuration. So you deliver more Web Services / APIs with fewer, less specialized people — efficiency goes up.
2. Time and cost drop significantly.
3. Security, logging, and other low-level, relatively hard topics are handled centrally, so risk goes down and quality goes up.
4. Service health can be monitored and issues detected and fixed quickly, so loss of reputation, customers, or revenue is greatly reduced.

A few benefits that are less obvious if you've never used an API Gateway:

• You can answer: How many Web Services do I have? Who is calling them? When and why did we open each one? What requests came in and what did we return? Which services fail most? Which are used most? How are they performing? What security measures are in place?
• Amount of code, and thus maintenance cost, drops a lot.
• Services become registered. You don't end up with services running somewhere nobody knows about.
• A service catalog emerges, so you avoid implementing the same service over and over.
• You can monitor performance and take steps to improve it.
• Service traffic becomes observable and reportable.

Conclusion

If you only have a few Web Services and use them for data exchange between your own applications — i.e. you are both provider and consumer — you may not need an API Gateway. But if the number of Web Services grows, you start building them for other organizations to call, or many of your applications act as clients to other organizations' Web Services, it's worth considering an API Gateway.