Skip to content

API Management Architecture – Architectural Considerations, Principles and Pitfalls


In the previous blog (API Management Architecture – An Introduction) I explained what API Management is and started explaining its architecture. If you have not read the first blog, I recommend you to read that one first in order to better understand this blog. This blog will go into the Architectural Considerations, Principles and Pitfalls. 

Read the first blog: API Management Architecture – An Introduction

Architectural Considerations

Value of having both SQL and NoSQL Database

The use of the NoSQL database is debatable and requires various aspects of considerations before we run both the RDBMS and NoSQL. I would highlights few aspects which might help us to think why we need a NoSQL in conjunction with the RDBMs.

NoSQL database like MongoDB or Cassandra can be used to store the API usage, rollup data, audit, metrics and system alerts. Remember the requirements, for each and every call to the API, the gateway need to write the logging details about the request/response it processed, not the exact payload but header details, http status codes, latency, time of call etc. Imagine that you are processing 1000 calls per second, which means quite a lot concurrent writings to the database. Also the data storage needs to be dynamic and flexible enough to scale up.  Now imagine this you have distributed API gateways across the geography and you need to localized the data read and write. It would be complex to set this up with available RDBMS in the market and also the cost that you need to bear.

This is where the NoSQL DB like MongoDB or Cassandra plays the role. Both of them are quite flexible in terms of scaling up the storage without much hassle as well as capability to store the huge amount of data. In my view, if the setup is complex and you need to handle tons of API calls per day, considering NoSQL for audit logging could be a design consideration you would like to give a thought.

Also I strongly feel that separation of concerns in terms of storing the logs in NoSQL vs configuration data to RDBMS makes sense, again depends on the setup and the organization needs.

I will write a separate blog around this for more detailed discussion.

Integration With External Identity Access Management System

Most of the API Management solution comes with the capability to store and manage the user credentials and to perform Oauth to issue the token. I would prefer avoiding the storage of the user credentials in the platform because you need to take care of securing the storage of the user credentials aligning to the data privacy policies. . If the enterprise do have the IAM on their own, then better to use that. This is also one of the aspect of architectural principle of separation of concerns where the user credentials and the roles and access are managed via IAMs. The IAMs will issue the token on successful OpenID or Oauth 3 legged to the user, the token is then submitted to the API calls to the API management platform. The platform then validates the token against the IAM and then allow the access.


The system to system access can be done using the platform authorization framework using oauth client credentails. Basically a client system will registered to the platform with a unique client ID and secret which will then exchanged to issue client credentials oauth token.

Protecting Client Side Apps

Protecting the client side APIs call via API Management platform seems to be a challenge. This is the scenario where the backend API calls to be made from browser via Javascript AJAX calls. These are non-authenticated API calls which are still need to be protected. The authenticated API calls can be protected using oauth 3- legged. Protecting non-authenticated browser based calls still seems to be challenge for us. Following are some capabilities that helps to prtotect these type of calls to a certain degree

Recaptcha – Using google recaptcha can be a way to protect the un-authenticated browser based API calls via API Management Platform. The recaptcha challenge would be present to an anonymous user in browser. The user successfully goes through the challenge and google issues a token back to the browser on successful validation. The token is passed to the API Management platform as part of the api call.. The platform will connect to google recaptcha verify API to validate the token and if valid then allow the call to the backend API

Brute Force Attack – The API Management platform provides some level of brute force attack prevention. Ideally there should be policy or rule available to identify the anomaly spikes and block the traffic from specified IP or ranges of IP. It can be configured for a pre-defined amount of time or forever.

A separate blog coming soon focused on this topic alone.

Other Considerations

Though the platform comes as a commercial off the shelf (COTS) product, there are few aspects that you need to consider while setting up the platform. First we need to segregate the components into localized and centralized components. These will help us to architect the whole setup of the platform thereby delivering high performance and scalability. Usually gateways are considered as localized component. They could be localized in terms of deployed in a different security zone as well as deployed as multi regional component located closely to the provider. All of these different gateways can communicate with the centralized policy manager, which manages different policies.

There can also be centralized API portal or community manager which registers and manages the API and different consuming applications across the organization. The community manager deploys the API to the right gateway.

Similarly lifecycle manager is also considered as a centralized, design time component which manages the lifecycle of different artifacts of API management platform across the whole environment stacks till production.

Let’s discuss in details in another blog.

Architecture Principles

Below are the certain principles and guidelines that help us to architect and design the API management platform to ensure we use the platform efficiently, effectively and use for right purpose.

a) Separation of concerns
An API management platform is a thin layer of security gateway intended to protect and manage the APIs. Any sort of business logic or building API should be avoided
b) Not a messaging layer
An API management platform is not a messaging layer and handling JMS messages should be avoided.
c) No orchestration
As mentioned earlier, API management platform should not be intended to use as a business logic platform, hence any kind of multiple calls orchestration should be avoided.
d) No Routing
Business decision to route the call to a different endpoint should be avoided. There should be a one to one relationship between API provider and consumer
e) No transformation
Transformation of payload should be avoided as much as possible to avoid performance delays.
f) Limited message enrichment
Message enrichment or adding headers might be needed and can be done. This is from security aspect where back-end expects security information which consumer should not provider. As a gatekeeper API management may need to provide those information on successful authentication.
g) Security
Must perform all sorts of authentication and authorization. It is quite possible that authentication and authorization is done by IAM. In that scenario the platform must validate the token against IAM.
h) Repository
Yes the platform should host the definition and documentation of API.
i) Accessibility
The platform should control the access of API by means of enforcing throttling, blocking the calls as needed.

Must-avoid Architectural Pitfalls

a) API Management = Integration Platform

An API Management platform is meant to manage your enterprise API, not to build APIs or integrate with external APIs or messaging system. I attended an API management workshop organized by various vendor and was shocked to see that the platform offers routing, transformation, external system connectors. While having those capability sounds lucrative, but those should be core part of the integration platform and should not be in the API management layer. Though the routing and transformation can be used but use selectively to meet the goal of your requirement.

b) API Management = all-in one security powerhouse

It’s quite tricky to decide what goes where and why. So clear architectural principles and guidelines would be needed to decide what security aspects that the API Management Platform will handle. Like all the other applications, API Management platform will reside into the application layer shielded by firewall and other application security mechanism. E.g The cross site scripting and XSS attack are best protected by the web application firewall, though API Management platform do offer those capabilities.

Similarly the DDOS protection are better done by the niche product rather API management platform.

Final Thoughts

With an increasing number of consuming applications and the APIs that organizations are building, it is imperative that we need a robust API management platform to manage, secure and analyze the use of APIs. Like any other architecture, it is quite important to follow guidelines and principles to manage the API management platform to get the best out of it.

Looking enthusiastically for valuable feedforward! Yours.

Discover our company culture

We are experts with a passion for technology and a drive to use it to achieve the best results for our clients, society and ourselves. We strongly believe that technical communities are the core of in

More about API Management

The digital ecosystem is evolving in many directions. Organizations are adopting multiple channels to drive newer sales channels, trigger new business models and generate more and more revenue. This triggers the need of unlocking business assets to the outside world in a secure manner. The increasing demand from Internet Business Models, IoT, social media and Cloud Adoption will exponentially increase the need to expose the business assets to the outside world by means of API.

Discover our company culture

We are experts with a passion for technology and a drive to use it to achieve the best results for our clients, society and ourselves. We strongly believe that technical communities are the core of innovation. Together we continuously explore the newest and coolest technologies. Are you ready to be a part of that?