Your API strategy stands little chance of adoption if you don’t have an API Catalog. But it’s more than a registry. Built the right way, it can drive innovation and collaboration for your digital initiatives.
API Catalog and the art of the possible
When I was very young, barely old enough to be able to throw a flip-flop up a flight of stairs, store catalogs fascinated me. Thick and formidable, these catalogs had it all — page after page of fantastic items — all arranged and logically grouped into sections with a massive index at the back for search and discovery of the very things that were going to make your life complete.
These catalogs fascinated me and my aunt took full advantage of this when she was tasked with looking after me and my sister. She invented a game called “Flip ‘N’ Flipper” in which we had to try to hurl a flip-flop up the stairs in our house. The higher the step we managed to flip, the better the reward: and that reward was a selection from the department store catalog. It was so exciting!
Of course, we didn’t really receive the items we selected, but it was the act of searching and finding the stuff we wanted that made it so compelling. It also made my mother grateful that she had a younger sister with such imagination to keep us busy and out of her hair for hours. Yes, these were the days before you could just hand a kid a phone or a tablet and be done with it!
I’ve taken this short trip down memory lane to remind you of the power of enabling the search, discovery, and, ultimately the reward that comes with a catalog of appealing items.
Now, if you are struggling with your API strategy and scratching your head why all the APIs being developed by your teams are not appealing to their intended users and leading to the result you wanted, it’s time to look at how they are being offered to your world of API consumers, both business and technical. It’s time you got yourself a modern API Catalog and start leading people to the art of the possible.
The shopfront — your catalog mirrors your business and can even help reimagine it!
A great API Catalog offers views for both business innovators and developers. It’s way more than the “service registries” of the past. Don’t present endless pages of unordered lists of APIs. Your APIs are products in their own right to be proud of.
Each API should provide a distinct capability that your business provides and is now being unlocked for your customers or partners in a new and exciting way. APIs are the building blocks to build great new digital experiences and seamlessly connect your technology systems in a way you never could before.
Think about your favorite online retail catalogs. The mother of all of these, need I say it, is Amazon.com and other retailers have been playing catch-up ever since. Think about the experience of using your favorite e-Commerce platforms.
It would never do just present pages and pages of product results and expect the buyer to just sift through this to find what they need. Yet, this is what so many API programs are doing. Worse, many are not even using a technology platform made for the purpose and are directing people to spreadsheets and wikis. Yuck.
Managing this API product information can be daunting but that’s where great information engineering comes in. You can use taxonomies and harness the magic of metadata to help organize things. Make sure you pay attention to the fact that there will be different ways of classifying your APIs because there will be different audiences coming to your API Catalog for different reasons:
- Line of Business Managers and Digital Strategists — will be looking to see how they can innovate and take advantage of the value your APIs are unlocking.
- API Providers — IT Planners and Product Managers — will be looking for things to reuse and how your APIs can support the capabilities that are being asked for and the data to which they need access to deliver new digital and mobile experiences.
- API Consumers — Developers both in and outside your organization — will be looking to use your APIs directly and get access so they can do further innovation and build the digital products with speed and control.
There are people who are experts in organizing information. It’s often called Information Architecture or Engineering. Seek out their help. You probably have some in your organization. I had the pleasure of meeting one such expert, from Walmart Labs.
It is his job to ensure that the thousands of products that are onboarded to the Walmart marketplace and cataloged in their eCommerce platform are classified and described for effective search and discovery. One thing he said stuck with me:
“Your ability to do your job depends on your ability to be understood” – Sean Lightholder, Senior Taxonomy Manager, Walmart Labs
The same goes for the ability of your APIs to do their job. Here’s where the organization of your API Catalog can get interesting.
One large financial services organization I advised used their API Catalog to layout their framework for how they intended to break apart their monolithic legacy systems and deliver their banking capabilities as microservices. To make it fun they socialized this internally as the API Pokedex. If you’re a Pokémon fan, you’ll understand the parallels!
Another large healthcare company I worked with used their API Catalog to visualize a set of journeys they had mapped out to provide new, digital experiences for their health plan members, partners, and associates. By making this available as a view in the API Catalog, they tracked which APIs were contributing to specific initiatives and it gave them a more meaningful way to measure API use and reuse.
In essence, they re-imagined their business and used the API Catalog to help drive technology innovation in a directed way that is truly leading to improved experiences for anyone doing business with them.
There are also very good industry-standard taxonomies out there that break down entire industries by capabilities and can be used as classification systems for your API catalog including:
- Insurance: ACORD Capability Model
- Banking: BIAN Service Landscape
- Healthcare: FHIR®
- Telecommunications: eTOM
Come and get it — enabling self-service
Once APIs are organized, the API Catalog can become a living, breathing thing. You need to enable self-service to stop your core API teams from a bottleneck and enable continuous API management by multiple teams at scale.
In order to stop this thing from becoming a horrendous mess, you need to integrate the API Catalog with your API Lifecycle Management pipeline. If you don’t have a consistent way to drive the management of an API from conception to publication and consumption, then you have a bigger issue and the API Catalog won’t be of much use! READ MORE: API Management is about measuring value exchange across the enterprise.
As more and more APIs come on board, a great way to ensure that the quality of the information in your API Catalog is maintained is to implement an audit before API teams can publish — the no junk policy.
This works even better if you’re using API design tooling that can interrogate and validate your API specifications and provide guidance and feedback to the API designer so they can improve and enrich the information they provide to describe the API.
Not just documentation — the “Active” Catalog
So, what’s actually in the API Catalog in more detail? It should be more than just technical specification documentation. As proposed, you should, at a minimum be classifying the API in a meaningful way for non-IT users. This allows all stakeholders in your API strategy to see the value proposition of your API. READ MORE: 10 ways to modernize your API strategy.
You can also record non-functional requirements for your API such as service level agreements and expectations about security, performance, and availability. That should make a whole host of people in your company with skin in the game for governance happy. No more going off to compliance documents and governance checklists managed in content repositories that no one can find.
The API Catalog has to be part of your delivery pipeline, as well as a registry for search and discovery. We think of this as a Developer Portal and the place where developers come to subscribe to APIs as consumers but it’s much more. This can’t be a stand-alone thing — a silo of information.
An effective API Catalog is the single source of facts about your API from which you can drive downstream automation from your API design efforts directly to your build pipeline. Things change rapidly and digital transformation has accelerated software delivery lifecycles.
You can use the API Catalog to drive continuous API Management and finally implement an effective versioning strategy that delights your consumers instead of breaking things for them without warning. READ MORE: What are the key components of an API Management solution?
Catalog of the future — the unified Catalog
As much as we all love APIs, there are other ways of providing “interfaces” to the latent value locked in your core systems. You’ll have Managed File Transfer, business-to-business system connectors, and other things that move data across your enterprise and outside its boundaries and you can represent these “products” alongside your API products in what can be thought of as a “Unified Catalog” to drive further innovation. Imagine the time and money your business can save having this available all in one place?
Additionally, your catalog can provide a common view across all of your APIs regardless of where the services those APIs are fronting are running. This is going to be a critical capability as organizations move more applications to the cloud while still trying to manage and integrate with existing capabilities on-premise. READ MORE: Get the facts: Learn all about hybrid integration here.
There are lots of gains to be achieved including:
- Consolidated Authentication/Authorization Handling hiding your internal complexity
- Central Traffic Management
- Monitoring, Alerts, and Insights into API consumption
- A consolidated way to register and onboard consumers
- A way to implement effective versioning strategies
- A resource for support and helpdesk teams to help consumers through usage and adoption issues
Additionally, the API Catalog of the future will not just show APIs as individual stand-alone products but will offer views on how they are combined and recombined into new, innovative digital products. An example would be a view that shows how a healthcare provider offers a “Health Lifestyle API” that also makes use of a Membership API, a Health Plan API, and a third-party health device API, e.g., Fitbit.
Doing that kind of innovation without a great API catalog would take much longer and that’s the time most companies no longer have to compete in the digital economy. A large healthcare provider I partnered with calculated that they saved 100 hours per product delivery this way.
Further things to watch out for:
Gamification and Social Media
Gamification is a great way to motivate people and, if enabled within an API Catalog, could drive adoption in an exciting way with friendly competition between teams. Again, the measurements would need to be meaningful but, coupled with social media features such as being able to rate APIs and give feedback through forums, it would be a great way to promote new APIs coming online and to communicate wins and business value.
Don’t forget the measurement
Speaking of communicating wins and business value, the API Catalog can help you measure what matters. It can be your command center for how you drive improvements in API delivery and measure how your API delivery is directly contributing to business outcomes like increased revenue and improved Net Promoter Score (NPS).
Given that your API Catalog should just be one component in an overall API Management Platform, you’ll be able to measure not only the running aspects of your APIs but improvements in how quickly you can deliver those new innovations. READ MORE: Learn how to innovate to accelerate digital transformation.
Take these ideas and look to make your API Catalog part of a bigger API strategy and collaboration platform for continuous API Management that really leads to API adoption in your organization and the innovation you need.
Happy Cataloging!
Let’s take it a step further, read all about how API marketplaces and API Catalogs are all about innovation.