All APIs should be listed and browsable inside a unified API Catalog. That sounds too good to be true, doesn’t it? Unfortunately it takes a little bit of effort to create an API Catalog but the results can be tremendous for Consumers but also Providers resulting in less effort and cost.
Why should i start to create an API Catalog?
The first and foremost reason is that without a central place for all your APIs you have to start searching where your APIs are. Required documentation, API Definition and Implementation kick starters or other important things can be difficult to find. Developers might create the same or similar APIs multiple times because it was not known that there is already an implementation existing.
And that’s just the inside perspective. What about somebody from outside your Enterprise looking for a smart way to integrate and connect with your business? Who to call, where to search, where to ask a question? Usually this leads to people going different places in order to solve their requirements.
How to create an API Catalog?
First you have to find and identify APIs in your organization. Then the next step is to start working on a compelling reason for people to bring these APIs. Ideally you have a way for people to register APIs themselves into the API Catalog. It helps not only to allow people to bring their Swagger, RAML or WSDL Definitions but also other information and artifacts that are helpful when consuming or implementing with the API. In first place you can help registering APIs into the Catalog. While API consumption grows, people will use the system more and more supporting your initiative.
Tools that come handy to create an API Catalog
API Lifecycle Management Platforms help with creating an API Catalog supporting Self Service API registration including approval and notification workflows for Providers and Consumers. These Tools also allow to separate between internal and external Consumption, enforcing Security Settings like Authentication Schemas, Rate Limits and Quota Settings. Usually Monitoring and SLA Management can also be enabled to provide more insights into API Consumption.
What about the Consumers?
API Developer Portals help to provide a meaningful and complete way for Developers and Implementers to browse APIs, request access and generate API Keys and OAuth Tokens which help securing access and identify different consumers for Monitoring and Analysis. But it does not stop here. Help, Support, Latest Information and SDKs can support your API Catalog initiative too.
Single API Catalog vs. multiple API Catalogs?
In some cases and larger Business people start thinking about creating Catalogs for each Business Unit or Department. I usually suggest to stay away from these separations as long as there is no Regulatory or Compliance Requirement for this. Modern Platforms allow to grant API Consumers access to sub parts of the Catalog or to partition the Catalog in multiple pieces according to lines of business or data that is exposed. A good Tag or Category Management inside the API Lifecycle Management Platform can help you satisfying requirements for multiple Catalogs but still running the Catalog in a shared service mode.
What other gains can I achieve?
If you have a central API Catalog you can start to propose multiple very valuable things like:
- Consolidated Authentication / Authorization Handling hiding your internal complexity
- Central Traffic Management
- Monitoring, Alerts and Insights into API Consumption
- a consolidated way to register and onboard Consumers
- API Versioning Strategies
- Support, Helpdesk for Consumers
In summary creating a central API Catalog can help reducing costs and friction of API usage but also providing a better experience internal and external.