These days API Management is an essential part of any API integration solution, while the API Catalog is an essential part of any API Management. 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 unique and very practical value of those specific capabilities.
How flexible is 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 placed 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 not only a better visualization, but also more flexible access control to different tree branches of your API Catalog by different API Management users.
A simple practical example: an organization that uses 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 different teams working on different API projects, members of these teams can be granted access and visibility only to a particular subtree hierarchy, while administrators can still access, monitor and manage the entire API Catalog, all 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 Gateway(s). 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 a number of significant limitations on the value of that API Catalog:
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”, and if registered and maintained in your API Catalog as “first class citizens”, they provide invaluable means of knowing what you really have developed as part of your API projects.
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 metadata and documentation which can be different from your original backend API’s. 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.
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 (may be 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 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) 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.
Even stronger benefits 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 the 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.
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 API Catalog really for APIs only?
It is much more practical and beneficial if 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 APIs’ 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 capabilities listed above, its User Interface can be turned into a very intuitive and effective tool. Drag-and-drop, interactive diagrams, effective Catalog searches are just few to mention.