API Catalog vs Holistic API and Service Catalog
March 26, 2020| Reading Time: 5 minutes
In this post, we’ll take a look at the traditional API catalog (as part of a runtime API Portal/Developer Portal), and the limitations it has for large organizations looking to mature their API strategies in support of digital initiatives. We’ll also discuss how an alternative solution – a Holistic API and Service catalog (with API and Service abstraction), sitting upstream of CI/CD and runtime, better supports this use case.
Who needs to catalog their APIs and Services?Most enterprises are now focusing on developing new internal and external APIs to mature their API First strategies and support initiatives like digital transformation, IT modernization, and innovation. Therefore, they need a central location for all their APIs and Services (with rich metadata surrounding each), to ensure they are discoverable, reusable, and properly governed. This is where a catalog comes in.
The API catalog – what is it, and what are its limitations?An API catalog is traditionally implemented as an element of an API Portal/Developer Portal (often as part of an API Management Platform), to serve as a library for an organization’s approved external (public) APIs. These APIs are held with documentation and other information, to make consumption by other developers easy. This is great if you only have a handful of external APIs in your organization. However, the reality for many organizations, especially large enterprises, is that they require 1000s of external and internal APIs (and other types of Services) to expose existing functionality in support of digital initiatives like innovation, IT modernization, and digital transformation. A runtime API catalog as part of an API Portal/Developer Portal has major limitations for this use case:
- It’s not cataloging all your assets, only a handful of them – the rest are hard to discover
- Your APIs and Services aren’t reusable or futureproofed – they’re held as implementation-specific code
- Only the external, well-crafted ones are properly governed and standardized – and it’s hard to report on the governance state of the rest
- API Catalogs aren’t designed for speed and scale when it comes to your API and Service portfolio
- API Catalogs are often read-only – i.e. not tied to the API and Service lifecycle – modifying/evolving APIs is a manual process and takes up valuable developer time
Other approaches to API and Service CatalogsYou may recognize several other approaches to cataloging APIs and services:
- Siloed file-based systems
- e.g. Excel, SharePoint, and source code repositories
- Digital Workflows
- Legacy Service Catalogs
- e.g. WSRR, CentraSite, and Akana
What is a Holistic API and Service Catalog? How is it different from an API Catalog?There are 3 key differences between an API Catalog and a Holistic API and Service Catalog:
1. The holistic catalog is for ALL your digital assets
Unlike a runtime API Catalog, a Holistic API and Service Catalog allows you to import, organize, and manage all your digital assets:
- Greenfield and Brownfield APIs and Services – Definitions and Specifications (WSDL, XML, Swagger, OpenAPI, Avro etc.), Operations/Methods
- Information models
- Taxonomies (business, technical and capability) and glossaries
2. APIs and Services are abstracted and held as Designs
With traditional API Catalogs as part of a runtime API portal, your APIs are held in runtime- and implementation-specific code, whereas with a Holistic API and Service Catalog, APIs and Services are held as abstracted Designs. Abstracted Designs are a separate artifact, and are code- and platform- agnostic views of your Services, which represent your business and IT functions. They contain important metadata and a target state of abstracted functions (what the API or Service does/will do (e.g. create, read, update, and search)). Designs also contain Specification(s), which are the representation of the Service, and contain all the technical details and further metadata (e.g. NFRs, lifecycle state, service owner).
3. The Holistic API and Service Catalog sits upstream of you CI/CD and runtime systems
Unlike an API Catalog, a Holistic API and Service Catalog sits upstream of runtime and CI/CD. It has a unique spot in an integrated velocity framework, acting as a bridge between upstream workflows such as Domain Driven Design (DDD) and Product/Project requirements outputs, and downstream CI/CD and platforms, through direct integrations.
Key benefits of choosing a Holistic API and Service CatalogThere are 5 key benefits of using a Holistic API and Service Catalog as your primary catalog over a runtime API Catalog:
1. Coverage – By importing all your APIs and Services into the Holistic Catalog, you’re exposing gaps, reporting on business coverage, showing the groups that are most influential, if your Services are meeting standards, and the interactions between them.
2. Discoverability of APIs and Services – As you capture all the details surrounding the APIs and Services (e.g. alignment to business/technical taxonomies, lineage and inter-dependence), assets are easy to discover and understand at various levels of granularity.
3. Reusability of APIs and Services – Your APIs and Services are arranged as bundle-ready building blocks, representing your business and IT functions. These building blocks can be approved for reuse, and can be leveraged to enable self-service bundling into new Product Bundles for new digital products. The Holistic Catalog of bundle-ready building blocks helps reduce duplication, and also helps widen the audience of your APIs and Services throughout the enterprise. Time- and cost-to-market are massively reduced, supporting the successful delivery of key initiatives such as innovation, IT modernization, and digital transformation
4. Governance and Standardization of APIs and Services – The fact that you’re holding APIs and Services as abstracted Designs, coupled with the fact the Holistic API and Service Catalog sits upstream of the CI/CD pipeline, enables governance and standards to be baked-in and applied throughout the API and Service lifecycle (and the catalog supports other API governance best practices too), generating normalized code and providing scale in a consistent way to deliver APIs and Services
5. APIs and Services become futureproof – Your system of record for your APIs and Services is no longer code, it’s now the abstracted Designs. This means you’re adaptable for any future technology shifts (e.g. the move from SOAP to REST) – your assets are future-proofed and free from technical debt.
By choosing a Holistic API and Service Catalog with abstracted Designs over a runtime API Catalog as your primary source of truth for your APIs and Services landscape, you’re setting up your enterprise for success. With all your assets in the holistic catalog aligned to business/taxonomy standards, properly governed and standardized, surrounded with rich metadata, and organized as reusable bundle-ready building blocks, you’re able to become a responsive digital business. You’re able to rapidly mature your API first strategy and deliver on key initiatives like innovation, IT modernization, and digital transformation.
For a deep dive on the Holistic and Abstracted API and Service CatalogFor more information on the Holistic Service Catalog, how it works, and the value it brings, check out our free whitepaper here.
The whitepaper covers:
- Approaches to cataloging digital assets to date, and the shortfalls of these methods
- What’s in a Holistic Service Catalog
- Why abstracting your assets is key
- How to import existing assets into the Holistic Service Catalog
- The key benefits of a Holistic Service Catalog in detail
- Governance and Standardization
- A capabilities checklist to measure your own organization’s maturity against