Introducing ignite 7® Watch On-Demand Webinar

digitalML Blog: The Key to the Intelligent Enterprise

  • API Strategy
  • Banking and Payments
  • Innovation
  • Insurance and Healthcare
  • IT Modernization
  • TechTrends
  • Generic selectors
    Exact matches only
    Search in title
    Search in content
    Search in posts
    Search in pages

    API Catalog vs Holistic and Abstracted Service Catalog – Which is Better?

    March 26, 2020


    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 and Abstracted API and Service catalog, 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
    Thankfully, there is a better option, which sits upstream of CI/CD and runtime – a Holistic and Abstracted Service Catalog.

    Other approaches to API and Service Catalogs

    You 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
    These too each have their limitations for large organizations who are trying to build and manage the 1000s of APIs and Services they need (you can find more detail on these in our whitepaper).

    What is a Holistic and Abstracted Service Catalog and how is it different from an API Catalog?

    There are 3 key differences between an API Catalog and a Holistic and Abstracted Service Catalog:

    1. It’s a catalog for ALL your digital assets

    Unlike a runtime API Catalog, a Holistic 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 and technical) and glossaries
    In addition to this, each asset is surrounded with rich metadata and aligned to business/technology taxonomies (at both the Specification and Method level) for discoverability and rationalization.

    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 and Abstracted 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 catalog sits upstream of you CI/CD and runtime systems

    Unlike an API Catalog, a Holistic 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 a Holistic Service Catalog over an API Catalog

    There are 5 key benefits of using a Holistic Service Catalog as your primary catalog over a runtime API Catalog:

    1. Coverage – By importing all your APIs and Services into a Holistic and Abstracted 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. The 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 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 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 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 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 Catalog

    For 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
      • Coverage
      • Discoverability
      • Reusability
      • Governance and Standardization
      • Futureproofing
    • A capabilities checklist to measure your own organization’s maturity against
    About the Author
    AvatarGemma Sindall
    Gemma is a Marketing Manager at digitalML. She has a keen interest in digital strategy and the best ways to merge people, process and technology. Her experience spans Marketing and Client Services in the Technology and Financial Services industries.