These days API Management is an essential part of any API integration solution, while the API catalog is an integral part of any API management tool. In this article, I will talk about some specific, often overlooked capabilities of an API catalog when selecting API management products. I will also emphasize the unique and practical value of those capabilities.

How Flexible is an API Catalog’s Structure?

It is quite typical to see API management vendors offering API catalogs as a “flat” list of APIs. This is the most primitive and limited structure because it does not allow easy grouping of APIs by some meaningful criteria. A much more practical presentation is a hierarchical tree structure. With such a structure, APIs in a catalog are arranged in tree-like “folders,” where each folder may designate any meaningful grouping criteria, such as your company’s project, sub-project, environment, or purpose of usage (like public vs. internal APIs). Even though grouping can still be achieved through APIs tagging, having APIs in a tree-like structure gives a better visualization. It also provides more flexible access control to different tree branches of your API catalog by different API management users.

Let’s consider a practical example. An organization using API management creates two folders for their APIs: one folder for APIs that are exposed publicly (Public APIs folder), and another folder for APIs that are used to integrate internal applications (Internal APIs folder). Each folder may have subfolders to define APIs that belong to different IT or business projects. If the organization has separate teams working on various API projects, members of these teams can be granted access and visibility only to a particular subtree hierarchy. In contrast, administrators can still access, monitor, and manage the entire API catalog from the same API management portal.

Can You Manage Backend (Physical) APIs and Virtual APIs (Hosted in API Gateways) Independently?

Many API management products offer the API catalog as a list of virtual APIs only — those which are hosted in API Gateways. Backend (or Physical) APIs, in this case, are not registered as independent entities in the catalog and can be seen only “behind” their virtual APIs’ configurations. This creates several significant limitations on the API catalog:

1. It is hard to identify the backend APIs you have under management because they are not directly part of an API Catalog (only virtual APIs are). Backend APIs are still your software “assets.” If registered and maintained in your API Catalog as “first-class citizens,” APIs provide invaluable means of knowing what you have developed as part of your projects.
2. Metadata (Swagger/OpenAPI Spec/WSDL) and documentation of the backend and virtual APIs may be different. Suppose your virtual service transforms messages while they fly through an API Gateway. In this case, virtual API consumers must be provided with metadata and documentation, which can be different from your original backend APIs. But still, you developed only the backend API (not virtual), and you want to know, at least for your own sake, its metadata and documentation.
3. Duplicate effort in creating multiple virtual APIs for the same backend API. Suppose you want to create two virtual APIs for the same backend API (maybe one virtual API for internal usage with internal endpoint and security policies, and another for public usage through public endpoint and its security policies). With the absence of an independently registered backend API, you would have to re-enter the same backend API’s configuration every time you create a new virtual API. Now, if your API catalog allows independent registration of your backend APIs, you can just reference (or link) a new virtual API to the same existing backend API. Moreover, if you happen to change something in your backend API (for example, change its endpoint address), you can do it once, and all dependent virtual APIs will automatically be notified and updated.
4. Even more substantial concerns arise when you deal with microservices architecture. You may create a single virtual API hosted in an API gateway that virtualizes (through aggregation) multiple backend microservices. Things get even more complicated when the same microservice is also part of different virtual services. For example, virtual API V1 virtualizes microservices M1 and M2, while virtual API V2 virtualizes microservices M2 and M3. If you have M1, M2 and M3 registered in an API catalog as independent entities, then you can just reference them by virtual APIs V1 and V2 instead of configuring V1 and V2 over and over again with the same backend APIs’ information.
5. There is no dependency tracking and impact analysis. You can have very practical, interactive dependency tracking diagrams embedded into your API management product if it allows independent registration of virtual and backend APIs. Dependency tracking also helps you to identify the impacts of any changes (for example, if I change a backend API – what virtual APIs will be affected and how?).

Is an API Catalog Just For APIs?

It is much more practical and beneficial if an API catalog can treat other types of API-related artifacts as “first-class citizens.” These can be security policies, access control rules (authorization logic), custom API behaviors, service-level agreements, etc. With this data at hand, you can identify dependencies between APIs and these artifacts, minimize required configurations and associated management efforts, promote re-use and consistency, and implement checks for compliances.

Conclusion and Final Notes

Implementing the described capabilities in an API management product increases the value of data it stores, which in turn gives more information and more power to IT and business people. Backend API discoverability, configuration re-use, change notification, and dependency tracking are some of the additional benefits offered by a properly designed API catalog.

If an API management catalog includes the capabilities listed above, its user interface can easily be transformed into a very intuitive and useful tool, with drag-and-drop, interactive diagrams, and effective catalog searches.