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

    Best Practices for a Holistic API and Service Catalog: Import, Organize, Normalize and Maintain

    September 1, 2020

      |   Reading Time: 7 minutes

    In a previous post, we looked at why a holistic API and Service catalog is a great solution for large enterprises looking to accelerate their digital and API strategy. A holistic catalog offers a unified view of all your digital assets (not just APIs but also legacy services (e.g. SOAP web services), information models, taxonomies and glossaries), upstream of CI/CD and runtime environments. However, some traditional approaches to cataloging have led to the idea that it’s hard to drive adoption and maintenance of a catalog. So, how do you ensure a holistic catalog:

    • Is up-to-date and properly maintained – providing a single and accurate source of truth for APIs and Services
    • Contains APIs and Services (and other digital assets) which are properly organized and easily discoverable by both technical and business users
    • Is used by roles throughout the enterprise – adopted by roles such as architects, developers, and product owners
    In this post we’ll look at the 3 key steps to a successful holistic catalog: importing, organizing, and normalizing your APIs and Services, and provide best practices when looking for a solution to ensure enterprise-wide adoption.


    Import, Organize, and Normalize APIs and Services, for a holistic catalog that is accurate and usable

    Import all APIs, Services and other digital assets into a holistic catalog

    A holistic API and Service catalog needs to be a complete source of truth for it to be used and considered reliable.

    Therefore, it needs to contain all your existing digital assets, including:
    • APIs
    • Services (including legacy SOAP web services)
    • Capability Taxonomy Models – both business and technical
    • Business Glossaries
    • Information Models
    • Provider Models
    It’s best practice to abstract your APIs and Services and arrange them as a set of Designs too, surrounded by rich metadata. This way they become easily understandable and adaptable for changing enterprise architecture (we’ll come back to these points later).


    3 ways to import APIs and Services into a holistic catalog

    In general, a comprehensive catalog solution will provide 3 ways of importing digital assets into the catalog, to make it as easy as possible to ensure it is a complete and accurate source of truth:
    1. Import APIs and Service en-mass through APIs/a batch import during initial set up
    2. Import APIs and Services individually through the solution’s UI
    3. Import APIs and Services through bi-directional integrations with runtime environments
    This ensures everything in your enterprise is brought into 1 location as a single source of truth: the holistic API and Service catalog.

    And what’s more, as part of ongoing use, having the holistic catalog enables you to support both top-down and bottom-up API and Service development, to ensure the catalog grows and expands correctly over time.


    Best practices for importing APIs and Services (and other digital assets) into a holistic catalog

    • Import all digital assets, not just APIs
      • Including legacy SOAP web services, information models, taxonomy models and business glossaries
    • Arrange APIs and Services as a set of abstracted Designs
      • Multiple versioned Specifications associated with an abstracted Design – code and technology agnostic
      • Business-friendly view of the API or Service tied to the technical-friendly implementation and code
    • Extensible custom metadata (custom data fields)
      • Surround the APIs and Services with metadata that matters to your organization (e.g. API or Service owner/group, region)
    • Enable upstream/downstream integration to the holistic catalog, typically with the CI/CD pipeline and distributed runtime (API gateways, event engines, etc).
      • As part of supporting top-down and bottom-up API and Service development, the holistic catalog helps ensure standards don’t get bypassed, while maintaining visibility of the Service through the API and Service lifecycle. This helps keep the holistic catalog up-to-date and reliable, and users know if the Service maintains governance compliance while moving from lower to higher environments.


    Organize APIs and Services to enable multiple types of API and Service discovery

    It’s one thing to have a holistic catalog, but if not properly organized, it’s hard to encourage enterprise adoption and maintenance. This is because API and Service discovery is limited, and it’s difficult to expand the usage of your APIs and Services to other roles in the enterprise (e.g. product owners).

    Most large enterprises are utilizing business and technical capability models, and these taxonomy models can be used to classify and organize your APIs and Services in the holistic catalog (we’re also starting to see people use process models and/or digital customer journey models which can be used in the same way).

    An effective way to do this is to classify APIs and Services at multiple levels (Design, Specification, Method/Operation) and enable more than one taxonomy node to be associated with an object.

    Once all your APIs and Services are classified, you gain a view into:
    • what functions and coverage you already have
    • what the coverage gaps are
    • who’s using existing APIs and Services
    • who owns existing APIs and Services
    • which APIs and Services need editing/modifying
    • which business and technical priorities you may need to push on

    A well-organized holistic catalog enables multiple types of API and Service discovery and widens the audience of your APIs and Services

    Once your holistic catalog is properly organized, by classifying APIs and Services to business and technical taxonomy models, you enable multiple types of API and Service discovery:
    • Enterprise
    • Line of Business
    • Product Owner
    • Consumer

    And discovery by different types of APIs and Services too:
    • Business and Technical Capability APIs/Services
    • Point-to-point APIs/Services (likely not reusable, and will be retired when the source system is retired)
    • Product Bundles (groups of reusable Specifications/Methods/Operations bundled together)
    • Facade/Experience APIs/Services
    • 3rd Party APIs/Services

    Not only have you enabled discovery, you can also expand the audience of your APIs and Services to roles throughout the enterprise. This is because:
    • You can provide a high-level summary of the API or Service and business views of the abstracted Design, for use by Business Executives and Product Owners;
    • and drill down from the summary and Design to technical details captured in Specifications (surrounded by rich metadata) and code views, for Business Analysts and Developers

    Best practices for organizing APIs and Services in a holistic catalog

    • Align APIs and Services to business and/or technical taxonomy models
      • Tag to taxonomies at multiple levels – Design, Spec, Method/Operation
      • And tag multiple taxonomies to the same object  (e.g. business and technical)
    • Provide business and technical views of APIs
      • Properly organized and understandable by everyone to aid enterprise multiple types of API and Service discovery, and widen the audience to new roles in the enterprise


    Normalize APIs and Services for a reliable holistic catalog

    In addition to importing and organizing, it’s important to normalize your APIs and Services to ensure your holistic catalog is reliable and actionable.

    While importing and organizing your existing assets gives a view into what you have, abstracting and normalizing APIs and Services within the holistic catalog provides reliability, and ensures the catalog expands correctly.

    For large enterprises with thousands of Specifications (and thousands of versions), abstracting and normalizing enables you to align your APIs and Services to a governance maturity model, provides flexibility on runtime platforms, and drives consistency.

    It’s also best practice to use a holistic catalog solution where you can capture lineage, versioning, and mapping information so that you have an accurate record of relationships between APIs and Services (and/or their versions).
    Combining this all with the fact that the holistic catalog is discoverable and reusable (by using a solution where APIs and Services can be marked clearly as approved for reuse), ensures that your APIs and Services are always reliable – driving adoption and usage of your holistic catalog.

    This gives you the gold standard to work from – a source of truth for APIs and Services with different views for different user roles in the enterprise with different actions available for the Service you’d like to use – combined with information on whether it’s in or out of compliance, reusability, ownership etc.


    Best practices for normalization of APIs and Services in a holistic catalog

    • Ease of search
      • Make API and Service discovery as easy as possible throughout the enterprise
      • Need various ways to search the catalog
        • for example free-form or filtered (which needs to be configurable)
    • Template-driven runtime-ready artifacts with bi-directional integration to CI/CD and run
      • Normalize code for reliability
      • Bi-directional integrations between catalog and runtime provides a single source of truth
    • Record lineage, versioning, and mapping
      • Consumes/consumed by inter-dependencies, orchestration and transformation, version changes, deployment records, updates from upstream/downstream systems
    • Bake governance models into the process to ensure API and Service maturity
      • Make it easy for product owners and developers to know what APIs and Services are in and out of compliance as they work through their plan, design, build and deploy process
        • this is faster and easier than manual and after-the-fact processes


    Once your APIs and Services have been imported, organized, and normalized, keep your holistic catalog up-to-date and maintained

    Keeping the holistic catalog properly up-to-date and maintained as the source of truth for your APIs and Services is critical too – it’s not a “once and done” process. This can be achieved through the following 3 best practices:


    1. Tie the holistic catalog to an extended API and Service lifecycle

    • Keep your managed Brownfield and newly designed Greenfield APIs and Services in one holistic catalog, aligned to the same maturity model for consistency between new and existing, whether they’re built by internal or external teams
    • Extensions/modifications to existing can be made to the Design, Spec, Method/Operation (with versioning and configurable rules on who can do what) and then Services re-deployed out (and provide a way to quickly flag to your organization which Services are approved for reuse)
    • The holistic catalog’s coverage grows as new APIs and Services are developed


    2. Leverage bi-directional integrations between your holistic catalog and CI/CD and runtime

    • Enables a change made in the runtime can be pushed back to an object in the catalog, and vice versa
    • Runtime information can be made available in the catalog (e.g. deployment history)


    3. Provide role enablement

    • A solution which enables both top-down and bottom-up development empowers a wide range of roles to help build out and maintain the holistic catalog – it becomes an integral part of the digital lifecycle rather than “just another piece of tech to use”
    • Easy-to-read abstracted Services are a code agnostic visualization, allowing multiple roles outside of the core engineering and development team to gain insight and understanding of data models, intended functions (and the Operations/Methods supporting them), and technical details used within each service. Thus, opening up the power of your existing holistic catalog to new and dynamic use-cases throughout your organization


    9 benefits to a well-organized and up-to-date holistic API and Service Catalog

    1. Enterprise API discovery

    • Everyone in the enterprise can understand the APIs and Services in the holistic catalog, and the audience is widened to multiple roles (e.g. product owner, LoB, executives, business analysts, provider and consuming developers, partners)

    2. Understand business and technical function coverage

    • Gives you a clear view of how your existing APIs and Services are encapsulating business and technical functions

    3. Reducing duplication

    • Easily discover existing APIs and Services (and their Designs, Specifications and Methods/Operations) which can be reused or bundled elsewhere

    4. Reporting

    • Regulatory and compliance reporting on your APIs and Services

    5. Business and value chain alignment planning

    • Based on all of the above – what needs to be built new, modernized, extended, or bundled to support digital business initiatives
    • API and Service discovery to visualize coverage and gaps

    6. Change management

    If you want to change something, easily visualize the other APIs or Services it will affect, therefore preventing breaks and bad consumer experience


    7. Reuse

    • APIs and Services become bundle ready business building blocks available for reuse
    • Maximizes return on API and Service investments by reusing in multiple products/functions

    8. Reliability

    • Source of truth where APIs and Services are easy to understand and consume

    9. Innovation and digital acceleration

    • Expanding the audience of your APIs and Services – expanded roles can use reliable business building blocks to bundle for safe innovation, launching new products and accelerating digital transformation
    • Number of reusable business building blocks greatly increased vs 10-100 external APIs in an API portal

    The ignite platform supports these holistic API and Service best practices and more

    the ignite Platform combines a holistic API and Service catalog which supports the best practices we’ve discussed in this post, with extended lifecycle management – accelerating the maturity of an API strategy and filling a gap large enterprises have in their digital landscape. To see ignite in action, or to discuss how you can implement these best practices alongside your existing priorities, book a digital roadmap consultation with us.
    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.