Introduction to Azure API Management

Recently in our company we decided to use Azure API Management service to improve security and scalability of our micro services landscape. In this and following articles I will try to dive into the subject and show different aspects of how this service can help to improve your system architecture.

I will start by covering basic ideas and definitions. In the upcoming articles I am planning to cover security of services and CI/CD pipeline integration.

Background

Azure API Management is a service that can serve as an API Gateway to your Azure services. Here I will briefly introduce the concept of Api Gateway Pattern. You can skip this part if you are already familiar with the topic. If you want to read more about the ideas and patterns — follow the links provided in description.

What is API Gateway

API Gateway is a pattern that aims to create a single-entry point for all clients, that hides the structure of micro services from the external world and that covers the common cross-cutting concerns so that there is no need to duplicate the logic across each service. It is often called as a “backed-for-frontend” and I personally thing that it is a perfect analogy. It helps you to write service without thinking of who and how will use them — client specific logic can be placed in APIM. Here you can find a great explanation of the pattern. I will also recommend following read that compares the direct client-to-service communication with API Gateway pattern.

Why to use it

The main benefits of using API gateway pattern are:

• decoupling client applications from micro services
• reduce the number of round trips by providing request parallelization and aggregation
• improve security
• single entry point, easier version management and services evolution
• can cover cross-cutting concerns and remove a need to repeat implementation of those across services

How to implement it

For a .Net ecosystem and Azure Cloud there are two main approaches to the topic:

• Azure APIM service — a build-in service in Azure. It is developed service with variety of options that can be overwhelming at beginning.
• Ocelot library — provides libraries and middleware that can be used to build API Gateway on your own as an ASP.Net Core service and easily integrate with Docker and Kubernetes. Both approaches have their pros and cons and which one to use is an individual case.

The subject is wide, and decision will never be simple. In our case we decided to use Azure APIM service. We see drawbacks and benefits of this decision, but our journey has just begun.

The API Gateway is a new thing to our company. We all knew that we will need it sooner or later, in this or another form. There were few independent projects that were planning to employ this pattern. One of new projects was typed to break the trail. Here I will describe an evolution of sample project, created for the purposes of this article and inspired by the journey we traveled.

Please note that this is a sample application, although inspired by real story, it is simplified just to illustrate the problems, sometimes in naive way.

Initial state

As a case study, imagine we have set of services and clients described below. It is an early stage and we expect it to grow fast in upcoming months. We expect new type of clients and services to come to the picture.

Services:

• Management service — managing settings and options. Aggregating statistics
• Device reporting service — devices will report data to it (measurements) in raw format
• Reports generation service — generating reports from gathered data

Clients:

• Web client
• Hardware devices

Requirements:

1. Hardware devices are reporting some statistics to the device reporting service
2. Hardware devices are downloading configuration updates from Management Service
3. User can check the statistics and turn on/off basic options by using Web client.
4. Web client is connecting with Management Service and Reporting Generating service
5. Management Service is connecting with Device Reporting Service to load data and Reporting Service to load reports history

This can be illustrated by following diagram:

Even the system is small, we have all services coupled and clients talking to at least two of them. Note that on the picture Management and Statics service are grouped. That is because both have many common parts, and to speed up initial development, decision was made to implement them as single service with functionality split internally. Ok, I hope we can agree that we have things to improve here and that the current state, if not changed, will cost us a lot of pain later.

In following sections I will try to fix those issues by utilizing APIM. Of course, those problems can be fixed in other ways, but as you will see at the end — both API Gateway pattern and APIM service work nice to help make your micro service architecture cleaner.

Adding APIM to the picture

As we have all our services hosted on Azure, we decided to use the Azure service called APIM (Azure API Management). First contact with it can be overwhelming. It is a huge thing, really. I got this task and after short time I thought that we are trying to use too sophisticated solution for a simple problem. It feels like an overkill! Fortunately, the more I worked with the APIM, the more I understand how useful it can be.

Here you can read how to create new APIM instance. After creating it, we can simply add our backend services as separate APIs by importing swagger files. Let’s ignore products, subscriptions and other features of APIM for now. Let’s assume also that we are not doing anything else at the moment than adding new service between existing ones. We need to change the endpoints in our clients to point to APIM endpoints. After all, the end state looks like simple proxy between clients and backend services. Sounds like a waste of time and money (yes, APIM is not cheap at all). But let’s go further with that.

Removing direct dependencies

In services description we identified three micro services. To meet the clients, requirements, we have coupled Management service with both services. Let’s focus on the dependency on reporting service which looks like something unnecessary. Our Management Service is calling it only to get the list of previously generated reports for a given user. You may ask why Management Service is doing that, not UI directly? Let’s say that this was because of two main reasons:

• authorization and data access filtering was already done in Management Service; we do not want to have this logic in web client and didn’t want to copy it to reporting service
• reporting service was being developed by different team, was in less complete stage and was not integrated with our Authorization services at all.

It is a common situation in modern software development that different services can develop at different pace, by different teams and with different technologies and architectures.

We tested two approaches to decouple the two services:

1. We pointed our Management backend to APIM endpoint for Reporting service. It doesn’t look good and introduced some additional round trips. But it was giving the expected separation. We were now able to develop both services independently.
2. Although we solve the problem, we were unhappy. We quickly change the solution to point client directly to the APIM endpoint of reporting service. By doing that we lost post processing logic and security rules. Thanks to liquid templates it wasn’t hard to move post processing logic to APIM. Losing a security was not an issue at this point — we were going to move it to APIM anyway.

The real power of APIM lies within policies. You can define variety of rules in different stages of request processing. Most of the things described in this article was done by defining proper policies.

We move forwards slowly. And we do not see a real power of APIM yet. You have probably a lot of doubts about what I did so far. I had them also. But please stay with me — the best is yet to come!

Virtual separation

Now is time for different story. I mentioned that we have two other services: Management and Device Reporting. However, those were run by single project because of early architecture decision. To not complicate things, it was decided to implement them in single service, and different methods were spread across controllers. Even after few months of development we still can’t agree if this was good or bad.

Together or not, we must treat respective services differently:

• we do not want to Web Client to access Device Reporting endpoints and vice versa
• we want to authorize Web Client and Device Client in different way
• we were considering applying different throughput or scaling rules for each

Looks like we are in small troubles and we need some architectural changes here! And once more we utilized APIM functionality to resolve our problem. We created APIM api twice from same swagger file, called them DeviceAPI and ClientAPI and manually adjusted endpoints in each. Below diagram illustrates the current state with more details. Also, I joined two services together to highlight the fact that there are served together:

Then we were able to set up proper policies in each of the api. We applied access restriction, and what’s most interested — later on we applied different security rules to both endpoint groups. Furthermore, we can now change the way we implement the services, split them up or introduce new ones, without need to update client. Imagine we split our big service to few smaller services like illustrated below — no changes required from the client perspective!

Backend — Frontend separation

There is also one more thing that is not clear from the pictures above. At this stage of application architecture, we have no direct dependency between any of the clients and any of the services. UI or Hardware client do not know anything about backend services and there is no direct communication between them at all. We initially developed our application using ASP .Net Core React template, and we got backend and UI in same project. Shortly after adding APIM between those two, we split them to different projects and finally with different repositories with separate release cycles and CI/CD pipelines. Sounds great, doesn’t it?

Optimizing performance

So far, we did not use APIM to improve performance of our system. It is too early for that. However, I want to mention two promising features of how APIM can help in this space:

1. Parallelization of calls — if our client needs to send few independent request to get data required to display a page, we can create a single APIM endpoint for it and let APIM internally do all the calls in parallel and combine the result for the client. That also remove the need of understanding the structure of service from the client (as we have our backend-for-fronted :)).
2. Add caching policies — APIM provides a simple add / read / remove from cache for response data that is relatively static. More to that it also enables you to use custom caching solutions for more advanced scenarios.

APIM help us to structure our application by forcing decoupling of clients and microservices. After presented changes we laid the foundations for a solid architecture that should nicely evolve with the system and adapt to new requirements.

I hope I manage to arouse your curiosity in the topic. When starting working with APIM for the first time, you need to be prepared for some challenges. However early discouragement should quickly pass away and you will begin to appreciate the benefits of this additional layer.

Originally published at https://dev.solteq.com on August 27, 2019.