The growth of application programming interface (API) adoption has led to a need for an API catalog to capture, organize, and manage APIs at scale. An API catalog is a type of technology that provides a searchable view of an organization’s APIs. This blog explains why an API catalog is necessary. It also provides a comparison between basic runtime API catalogs and an enterprise-grade Holistic Catalog.
- Why you need to catalog your APIs
- What is an API catalog?
- What is a Holistic Catalog?
- Holistic Catalog benefits for large enterprises
- Should you build or buy your API catalog?
- What about Developer Portals and API Marketplaces?
Why you need to catalog your APIs
The use of APIs has grown rapidly. This has caused “API sprawl”, with different types of APIs running across multiple systems. In fact, the average organization is now interacting with over 15,000 APIs.
API sprawl is a looming threat to the success of your API program. It can lead to duplication, higher security risks, and reduced API adoption and reuse. These are all serious concerns.
That’s where an API catalog comes in. Properly cataloguing your APIs into a single location can:
- Create a single source of truth for all APIs across the enterprise.
- Ensure you can successfully reduce duplication and redundancy.
- Improve API discovery and reuse as you can effectively feed curated content to your consumers.
- Understand what you have and how “good” it is by improving reportability and API metrics. Additionally, understand who owns it and where it’s running.
- Reduce security vulnerabilities by identifying and tackling threats such as zombie and shadow APIs.
- Help effectively manage the lifecycle of your APIs including lifecycle implications of multiple consumers adopting your APIs.
- Assist prioritization of business goals for your API program
So what exactly is an API catalog, and what catalog tools are available?
What is an API catalog?
An API catalog is a searchable inventory of your APIs and their supporting documentation and other metadata. The most common type of API catalog is offered as part of an API management platform. Runtime API catalogs can be useful for organizing certain types of APIs, such as public REST APIs. However, they can also present some common challenges.
There are some key limitations to a runtime-based API catalog, including:
- It will only capture the APIs running on the gateway it’s coupled to. Most enterprises are now running multiple API gateways, so even if you’re only trying to catalog OpenAPIs, an API catalog tied to one runtime won’t capture them all.
- It’s only for APIs, so you’re not creating a single source of truth. Other API types (SOAP, Events etc.) will need their own catalogs with this approach. Most enterprises have highly complex distributed environments, with APIs and services running in different versions on different gateways, Enterprise Service Buses (ESBs), service meshes etc. All these ideally need to be captured in one place.
- The APIs’ system of record (SOR) is held as code. This makes discovery, reuse, and iteration very difficult. Cataloguing APIs in this way also means you can’t easily bring in roles other than developers (such as product owners, business analysts) into the lifecycle and allow them to easily interact with your APIs.
- They are often a read-only catalog. The catalog must be connected to the API lifecycle management process. Without this connection, modifying or evolving APIs becomes a manual process. This consumes valuable developer time.
- They’re not well organized and optimized for both the provider and consumer experience. Most runtime catalog offerings have limited ways to organize your APIs and control who can see what. This becomes especially challenging for large enterprises with lots of API complexity. A junk drawer catalog is unlikely to be adopted.
- They need to be manually maintained and kept up to date. Again this is a time suck on valuable developer resource.
What is a Holistic Catalog?
A Holistic Catalog is an unique type of API catalog, and overcomes many misconceptions of catalog tools. The Holistic Catalog is located upstream in your API framework. It is positioned to the left of your pipelines and runtime platforms. This catalog captures not just your APIs but also other assets:
- All types of integration asset (e.g. REST, SOAP, Async, GraphQL) as well as Product Bundles (also known as API products)
- Business and Technical Capability Models and Taxonomies (which are used to organize your APIs)
- Information Models and Domain Models
- Governance Rules, API Documentation and Metadata, Service Endpoints, and Policies
- API Complexity such as lineage dependencies, data mappings and transformations, and orchestrations
ignite’s Holistic Catalog organizes APIs as abstracted Designs associated with versioned technical Specifications. These are aligned to your business capabilities so they’re easy to understand by all roles.
Why a Holistic Catalog is preferable to an API catalog for large enterprises
As a large enterprise, your API program is likely vast and complex. Here are some further benefits of choosing a Holistic Catalog over a traditional runtime API catalog:
- The Holistic Catalog takes an abstracted and technology-agnostic approach to cataloguing APIs. You can capture and manage all assets flexibly and responsively. The APIs are not restricted to the code they are implemented with. You can also therefore catalog APIs that are currently being developed, as well as those already in production.
- No vendor lock-in. APIs can be redeployed to any downstream target in any format (since they’re held in abstracted form), so you can quickly adapt to the ever-changing nature of enterprise architectures.
- It’s active and connected to multiple repos, pipelines, and runtimes. Meaning no need for manual maintenance. You can capture, organize, understand the consumption of, and manage APIs newly created by all your teams by automatically harvesting them from where they’re running directly into the catalog. Shadow and Zombie APIs are no more!
- Effective reporting and rationalization means you can make data driven decisions on your catalog. Identify your most valuable APIs to promote for reuse. Reduce cost inefficiencies of redundant and duplicate APIs. Identify gaps in capabilities that need new APIs to support them. Also consider regulatory reporting.
- The Holistic Catalog provides multiple views of assets for business and IT enablement. View your APIs in business, technical, application, taxonomy, data lineage and mapping views.
- Your APIs are properly organized with their complexity captured. You can have one catalog that supports all your Lines of Business (LOBs), regional teams, and internal, external, and partner APIs. Robust access controls ensure that only the right people are able to see and do what.
- Governance and security by default. Thanks to the Holistic Catalog’s automated and flexible API governance model, you can ensure your APIs are complete, consistent, and compliant. This ensures you’re delivering reliable experiences.
- The Holistic Catalog is part of a connected framework. It’s tied to optimized API lifecycle support so you can safely and seamlessly iterate APIs over time. It’s also connected to Consumer Portals, API Developer Portals, and API Marketplaces, to drive effective API consumption and reuse while maintaining tailored experiences for consumers.
Here’s a quick video to show more of the basics and benefits of ignite’s Holistic Catalog from our ignite Bites series:
Should you build or buy your API catalog?
Many enterprises debate whether they should adopt a catalog tool, or try and create an API catalog in house. We discuss the considerations in detail in our build vs buy paper which you can download below. But at a high level, our enterprise customers have found that by buying a catalog tool like ignite’s Holistic Catalog, they can focus on delivering value from their APIs themselves from the outset, rather than having to invest time and money in building the functionality that helps them do this.
What about developer portals and marketplaces?
Developer portals, also known as API portals or API developer portals, focus on socializing and consuming existing reusable APIs. API marketplaces have the same purpose.
Think of these as a storefront where your API consumers (be those internal, partner, or external) can find, evaluate, and subscribe to your gold standard APIs that support their use cases. Extending this analogy, your API catalog is the warehouse; a store for all your products, not just those you want to stock on your shelves right now.
We’ve compiled a comparison of developer portals, API marketplaces, and ignite’s new Consumer Portals in this blog for futher reading on this aspect of your API tooling framework.
API catalogs can provide a single source of truth for your entire API inventory. Traditional runtime API catalogs have several limitations for large enterprises using a variety of API types across multiple platforms. The Holistic Catalog is a unique approach to cataloguing APIs that overcomes these limitations. This enables you to effectively capture, manage, rationalize, govern, and reuse APIs at scale.