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

Is there anyone who does not remember this scene? Neo’s “Where the hell we are!” look, his appeal to Trinity… Just as he was getting out of the car saying “Well, I’ll walk away, why should I bother?”, Trinity intervenes and he stays in the car… 25 years have passed, it’s easier said than done! Anyway, it was a good movie. I should watch it again sometime.

If you ask what does that have to do with anything, the situation is somewhat similar to the above regarding API Gateway: We say “API Gateway or the code way”.

But this time, 1- no one will pull a gun on anyone, 2- we have time for questions.

In this article, I will try to answer questions such as “What does API Gateway do?”, “Why should we use API Gateway?” or “Should we use API Gateway?” in a way that those who have just started to develop Web Services can understand.

A little reminder before we start: Let’s not get hung up on the word ‘API’. The context of this article is Web Services and we will talk about Web Services used as APIs. While talking about Web Services, the terms like SOAP, WSDL, and XML come to mind when “Web Service” is mentioned and the terms like REST, Swagger and JSON come to mind when “API” is mentioned but in this article, I use both terms; i.e. I will use the terms “Web Service” and “API” interchangeably, regardless of the minor differences between them.

Let’s get a Web Service

Let’s start by writing a Web Service example. However, since the topic of this article is API Gateway, I leave the service development process to the following article: Explore the article, your Web Service will be up and running in about 5 minutes with SpringInitializr.

It doesn’t matter what language the Web Service is written in, whether it’s SOAP or REST. API Gateway can be used for all Web Services regardless of language and protocol.

So what’s the problem?

Is there anyone saying “Well, I wrote and ran the service in five minutes. How hard could it be to add a few more methods (endpoints)?” Definitely, there is. Now, of course, it is possible to explain something by giving code examples with cool terms such as Cross-cutting Concerns, Containers, or Proxy Objects. However, I will not go into this, as I think that we may lose our new friends at the beginning of the article. I think there is no need to even write them for senior fellows :). So let’s proceed more simply and verbally.

As you can see, developing a Web Service is not a big deal. “Services are not that simple in real life,” you may say but rest assured that it is usually not too complicated. Most of the time, by developing Web Services, we do nothing but make database operations, algorithmic solutions, or some already existing functions callable over the Internet/network. That’s what Web Service is all about: making a method callable via HTTP.

The main challenge with Web Services is solving the administrative problems that come with the rapid increase in the number of services and clients. A few examples of these:

1- Authentication: When you put Web Services on the server and open them to the Internet, you usually don’t want everyone to call them. In this case, you need to set up an authentication mechanism to allow only identified users to access it.

2- Authorization: As the number of Web Services and/or methods (endpoints) increases with the number of users, requests begin to come in the form of “those people should call these methods, but those people cannot call these methods”. You need to do authorization for this.

3- IP Restriction: It can be requested that only requests from certain IPs be accepted, or requests from certain IPs not be accepted. For this, you can request support from the network team and ask them to update the Firewall settings for requests coming to your service. But rest assured, there will be times when you need to add new IPs or change servers, migrate the service or add new servers and you will soon start having problems with the network teams.

4- Content Filtering: Do you think all requests are innocent? There may be attacks. How will you prevent them? Are you going to contact the network team again? Or will that be enough?

5- Encrypted Communication (Encryption/Decryption): Encryption of incoming and outgoing messages may be required. Unfortunately, we cannot just say “I opened the service with HTTPS, what is the point?”. Sometimes customers may say, “I would like it to be encrypted”. Sometimes, you may also encounter a demand such as “Let the requests be signed. Open and verify the signature and send it with a signature of mine.” Be prepared for that. In this case, the network team will not be able to help either.

6- Have you ever heard of WsSecurity ? There is a standard for all these passwords, open the password, sign, and verify things and this is used in SOAP services of some institutions. I wish good luck to friends who will write code to become a client of such a service.

7- Schema Verification: If the structure of the message we expect to be sent to our service is clear, for example, if we can say “I am waiting for an Integer in this field, I am waiting for a Date in that field”, shouldn’t it be necessary to check these as well?

8- Sometimes customers say: “I want my service to serve only on these weekdays and these hours, not other times”. How would you handle this?

9- Message Transformation: As the number of clients increases, requests such as “Can you change the structure of the message like this?”, “Can you not send null fields at all?”, “Send the strings like this.” start to increase and sometimes you can’t escape it, you have to do it.

10- Redaction: Your service is returning a response in a certain structure, but after a while, you will be prompted to make updates like “The following information will also be returned to users of this type, but others will not be able to see this information.” This time you have to either multiplex the services or write code to return a personalized response.

11- Logging: A log is required as well. Typical questions: “Who called?”, “When did he/she call?”, “What did he/she send?” “What did we send him/her?”, “To whom did we send this information?”, etc. It is not enough to keep logs, you are requested to be able to query.

12- Checking if the service is running (Monitoring): Let’s assume that you wrote a service that needs to be available 24/7. So how do you check whether it is still working or not and whether it returns a correct answer? What if it somehow stops, starts returning incorrect answers, or slows down and starts consuming timeout? How will you know about this? Will you wait for someone to complain through a phone call or an e-mail? Of course no! Some precautions have to be taken for these.

13- Error Messages (Error Message Handling): What error message or HTTP code will your Web Service return? How will you customize them? You may say “Is it necessary? Can’t we just return the message ‘an error occurred’ with the 500 code? ” No way! There are many clients and error messages need to be meaningful. If the error message does not tell the client that it has sent a missing parameter or that its IP is incorrect, how will the client know and fix the error? If you don’t want to receive a request like “I get this error and I can’t fix it, please help” from everyone by phone or e-mail and deal with it one by one, you should return meaningful messages.

14- Maintenance: Have you ever tried to update an existing system while it is running? Imagine this for your web service.

15- Service Transfer: You may need to change the address of the service for some reason. What if you have a large number of clients? Everyone needs to start using the new address by updating their code, or you need to make this change without making the clients realize it. The latter is much better, but how are you going to do it?

16- Load Balancing and Failover: As services become critical, the pressure will increase. It will be unacceptable for a service to become inoperable or decrease in performance, and this time you will want to install the service on other servers and create a cluster. Thus, both the load will be distributed to the servers, and if any server causes a problem, one of the other servers will respond to the request, so that the traffic of the clients will not be interrupted. Nice. So how will you do it?

17- As the number of services increases, even the follow-up of their existence becomes a problem. Before opening Web Services, some institutions are making protocols with institutions that will use Web Services. It is essential to manage which service is opened on which date, with which protocol, and how long the protocol is valid. Even sometimes this is requested to be done automatically. Good luck!

18- Documentation: How to use the services must be documented. Relying on standards such as Swagger or OpenAPI will make the job easier. Well, how many people, who read this article and develop/developed Web Services, have prepared at least one Swagger or OpenAPI file so far? Do you know the format?

I can add to these items, but for now, I think these are enough. If you’ve patiently read them all and stop for a moment and ask, “How do I do these?”, you’ve probably noticed how much work needs to be done other than coding the business logic of a Web Service. Of course, some of these can be handled by coding. However, you should keep in mind how many people in your team can write code at this level, that the number of Web Services may not be 1, but 100, 200, 500, and all the code written will need to be maintained. And get away from that urge to solve everything by coding!

I have prepared the following drawing as a summary of what I have covered so far.

Coding business logic and deploying Web Service is the tip of the iceberg. The real business is under the surface and ignoring these can be a fatal mistake (Look, now I think of Leonardo. Boy, you should have gone with the girl, why are you being a smart-ass and freeze yourself?!).

What does API Gateway do?

API Gateway is the common name of the software that helps to solve the above-mentioned stuff and many more by configuring the Web Services without touching the code. It is put in front of your Web Services and the message traffic of Web Services passes through API Gateway. Thus, any kind of control, transformation, or customization of these messages becomes possible.

As seen in the figure, the request sent by the client (Step 1) is met by the Proxy on the API Gateway. Proxy is the proxy entity created on the API Gateway for the Web Service to be accessed, and the Client communicates with the Proxy. The Proxy becomes a client to the Web Service (Step 2) and receives the responses returned by the Web Service (Step 3) and returns a response to the Client (Step 4). Through the configurations made with the API Gateway software, the behavior of the Proxy is customized, and thus security, traffic management, message conversions, service transfer, and similar requirements can be managed from a central point.

It is also important that an API Gateway software has features such as low latency, high performance, and scalability, as well as providing easy-to-use interfaces, being able to be positioned so as not to cause a Single Point of Failure, and supporting a large number of users in different roles. Depending on the need, it can also play an active role in the preference of an API Gateway, as it can integrate with or offer different and various tools/software.

We can summarize the obvious benefits of being able to do all these things with configuration only:

1- Web service development is reduced to coding business logic. Configuration alone is done for all the remaining needs. Therefore, it is possible to develop and offer more Web Services/APIs with fewer and less specialized personnel, and efficiency increases.

2- Time and cost are significantly reduced.

3- Low-level and relatively difficult issues such as security and logging are handled centrally and are much easier to control and perform. Therefore, mistakes that novice software developers can make are minimized; risk decreases, quality increases.

4- The status of the services can be constantly monitored and errors can be detected and resolved immediately. Thus, loss of prestige/customer/money is significantly prevented.

Let’s not finish without mentioning a few of the less obvious benefits for those who haven’t used API Gateway:

1- The following questions will be answered:

  • How many Web Services do I have?
  • Who is accessing my Web Services?
  • Which one did we open? When and why did we open it?
  • What request came, what response did we return?
  • What are our most error-prone services?
  • What are our most used services?
  • How is the performance of our Web Services?
  • What security measures have we taken?

2- The amount of code and therefore the maintenance cost is significantly reduced.

3- Services become registered. There will be no services running somewhere that you are not aware of.

4- Service catalog is created. This solves the problem of overwriting the same services over and over again.

5- Measures can be taken to increase performance by monitoring the performance of the services.

6- Service traffic becomes monitorable and reportable.


You may not need an API Gateway if you only have a few Web Services and use them to exchange data between your applications, i.e. you are both the provider and the consumer. However, if the number of Web Services increases, if you start to develop Web Services for other companies/institutions to call, or if you start to become a client for Web Services developed by other companies/institutions, it is useful to consider using an API Gateway.

If you want to try one out quickly, we have one that we’ve been working on for a while: