All successful digital enterprises are now focusing on developing new internal and external APIs to mature their API First strategies, increase digital agility, and support initiatives like digital transformation, IT modernization, and innovation.
You’re likely expanding both the number and types of APIs (including newer styles like events-based APIs), while also working to maintain (and where appropriate modernize) legacy like SOAP web services.
That’s why cataloging these APIs (plus Events and Services etc.) is an important initiative for enterprises.
Effective cataloging can:
- create a single source of truth
- improve API discovery and reuse
- and assist with consumer onboarding.
But there’s some different approaches and tooling. After reading this blog you should have a good idea of which is right for you – utilizing an API catalog, Developer Portal, and/or a holistic catalog.
API Catalog, Developer Portal, and Holistic Catalog Definitions
First, let’s run through what we mean by each offering, and typical use cases for each.
A library of external and/or internal APIs, along with some documentation and metadata. Most commonly a feature of an API management platform. The APIs in this type of catalog are held in implementation-specific code.
There are some key limitations to a runtime-based API catalog, including:
- It’s only for APIs, so you’re not creating a single source of truth – other service types (SOAP, Events etc.) will need their own catalogs. Most enterprises have highly complex distributed environments, with APIs and services running in different versions on different gateways, ESBs, service meshes etc. – all this needs to be properly captured.
- The APIs’ system of record (SOR) is held as code – this makes discovery, reuse, and iteration very difficult. Cataloging 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 – i.e. not tied to the API lifecycle – modifying/evolving APIs is a manual process and takes up valuable developer time.
Best use case for an API catalog: Your enterprise:
- only needs to catalog APIs (and likely only those in OpenAPI format)
- only has API-centric runtime environments and gateways
- only wants developers to interact with your APIs
Developer Portal (also known as an API developer portal)
A branded hub (normally a website) where consuming developers can subscribe to your enterprise’s open APIs. Sometimes called an API developer portal, or API portal. Think of it as a shop front for the business capabilities you’re exposing to the world that consumers can integrate into their own applications.
Typically an enterprise will have 10-100 open APIs in their developer portal.
The portal contains documentation to help consuming developers find and understand the APIs, as well as functionality like trying the API out/API mocking, and subscription management so developers can authenticate themselves and subscribe to your API(s). It also contains technical information for development using the API, like rules and SDKs.
The developer portal is populated with APIs from the overall catalog (either the runtime API catalog or holistic catalog depending which use case suits you best. While they’re great for ensuring great consumer experience for your external, or open APIs, you wouldn’t hold your entire portfolio of all API, Service, and Event types in your portal!
Best use case for a Developer Portal: You need a portal for your open/external APIs where consuming developers (e.g. application developers) can find, understand, and subscribe to them.
A holistic catalog brings all your digital assets into one place for a unified source of truth. Assets including:
- APIs, Services, Events (REST, SOAP, etc.)
- Business and Technical Capability Taxonomies (which are used to organize your APIs)
- Information Models
- Dependencies and relationships between APIs (lineage and mappings)
A key difference between a holistic catalog and an API catalog or developer portal is that the holsitic catalog sits upstream of API gateways and your distributed runtime environment:
This approach allows for your APIs, Services and Events to be abstracted away from code and organized as Designs (with associated Specifications to capture the technical details for the service interface). These can be classified according to your taxonomies so they become organized digital business building blocks.
Your assets are surrounded with extensive configurable metadata, which drives discovery and reuse. Most importantly, it enables discovery and reuse by many roles in your organization, not just developers.
Best use case for a Holistic Catalog: You’re a large enterprise with lots of API, Service, and Events that you want to bring together for a single source of truth across your digital landscape, and organized as reusable digital building blocks. What’s more, you want multiple roles across the organization (and ecosystem) to be able to find, understand, and interact with your APIs, Services, and Events – as well as the lifecycle (where appropriate).
As Gartner cover in this report, it’s becoming difficult to cover all use cases with a single approach. Here at digitalML, we’re seeing Global 500 enterprises successfully implement a holistic catalog (like our ignite platform) for the system of record of all APIs, Services, and Events, with a runtime developer portal for their external open APIs.
Further benefits of the Holistic Catalog
There are some further critical benefits to a holistic catalog that can help differentiate your enterprise as a digital leader:
- Understanding business and IT function coverage – for better strategic prioritization.
- Consistent, compliant, and complete APIs, Services, Events – the holistic catalog facilitates alignment to an enterprise-grade governance model, to ensure your assets are high quality and reliable.
- Aligned to the lifecycle and integrated with CI/CD and run – so your catalog is always in sync and accurate.
- 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.
- Reportability – as your catalog is the source of truth for everything (not just APIs), you can easily report on the state of your digital landscape, to internal and external stakeholders (including regulators).
For a deep dive on the Holistic Catalog
The whitepaper covers:
- Approaches to cataloging digital assets to date, and the shortfalls of these methods
- What’s in a Holistic Catalog
- Why abstracting your assets is key
- How to import existing assets into the Holistic Catalog
- The key benefits of a Holistic Catalog in detail
- A capabilities checklist to measure your own organization’s maturity against