The Case for a Separate API Catalog and Multiple API Consumer Portals
To deliver the promises of an API-first world such as increased revenue opportunities and innovation, and greater operation efficiency, enterprises are looking for ways to better drive API adoption and reuse. In addition, the proliferation of APIs in enterprises mean they’re also looking to capture, manage, and make business decisions on their entire API inventory.
There are two key architectural components in delivering these initiatives; the API catalog and the API consumer portal. Many think of these as having overlapping use cases, and therefore likely to be supported by the same tools and capabilities. But to drive effective API management and adoption at scale, in reality the best practice pattern is to have a separate catalog of all your APIs, supporting multiple portals in an active, connected, and seamless way.
Understanding API Catalogs and API Consumer Portals
Firstly, let’s define what an API catalog and portal are (we recently compared the two in a post on our blog if you’d like to know more detail).
An API catalog is a centralized repository for all of your APIs across the enterprise. It should contain all types of APIs (e.g. OAS, SOAP, Async, GraphQL) in various lifecycle states from ideation and development to deprecation. It also captures metadata and other key artifacts such as documentation surrounding each API. It’s the central hub to manage, govern, iterate, and make decisions on your entire API inventory.
An API consumer portal (also known as an API portal) is the interface your API consumers use to discover, evaluate, and onboard your best APIs that have been made available for adoption and reuse. It should provide a user-friendly experience for consumers to find relevant APIs, decide if it meets their use case, try the API and confirm they want to take on its dependency, and easily gain access to and integrate the API into their applications.
Traditionally, there’s been some confusion about these components, and we’ve seen enterprises trying to do both use cases with one tool. Alternatively, we often see enterprises with one catalog and just one portal. These approaches can lead to some key pain points such as:
- Irrelevance and clutter in your portals. Making it hard for consumers to find what they’re looking for, thus affecting adoption rates.
- Poor user experience and optimization. With a combined approach, it becomes harder to optimize the system for specific user needs, which can stifle innovation and efficiency.
- Hard to serve different consumer audiences. Since different types of consumers have differing expectations for the portal
To deliver the promises of an API first world at scale and overcome these pain points, the catalog and portal need to be distinct entities. The catalog is like your distribution warehouse where you manage the entire API inventory. Meanwhile portals are your tailored storefronts where you offer best-of-breed consumption experiences and views of the APIs you want to put your brand to.
Specifically, multiple portals powered by one catalog is a best practice for success.
The Case for one API Catalog separate to the API Consumer Portal
Having one holistic API catalog as its own entity in your API architecture framework provides you with centralized management of your entire API inventory. You gain one single location for all APIs across all runtime, surrounded by metadata, documentation, and other artifacts. The catalog can also be home to your governance rules, security policies, domain models, and business and technology capability models. All this in one place helps make it easier to organize, govern, and manage all your APIs from one place.
The catalog is for everything in your API landscape
In addition, enterprises tend to have large and complex inventories. Of course, not all these APIs will be reusable. For example, you’ll likely have 100s-1000s of APIs including legacy, point-to-point integrations, and those in earlier lifecycle states currently being developed. Your catalog has everything in it and while you might not want to expose all of it for consumption, you do want to be able to manage and provide visibility into it.
Put simply, not all your APIs will be customer-worthy experiences, and having all of this in an API portal would clog up the consumption interface. Instead, you want to expose only the APIs supporting business and technical capabilities that are gold standard and consumer-centric.
Separate catalog; better security
Having a catalog separate from the API consumption interface provides better security and control of intellectual properly (IP), too. Especially if you’re exposing APIs to external facing portals, you wouldn’t want the entire API portfolio available. This ties into the case for multiple API portals, which we’ll discuss shortly.
Unified API metrics
A catalog done right can mean better enterprise decisions thanks to better API reporting. The catalog serves as a location for design, runtime, and consumption metrics to be unified together. This gives an accurate and active view into how the portfolio is performing, and helps you answer questions like:
- What are our best candidates for new products and services and/or new revenue streams?
- What’s our API coverage against our business capability model?
- What’s “good” against our API governance rules and enterprise standards?
- What security vulnerabilities do we have? And how can we fix them?
- Which APIs are out in the wild and not yet in our catalog?
- Which APIs might be suitable for curation and reuse?
- What adoption/consumption is happening?
- Which APIs might be suitable for refactoring to a more efficient protocol e.g. WSDL to OAS?
- Can we make any savings on our API gateways by migrating APIs from one to another?
Improved scalability, versioning, and other API management best practices
Having the API catalog as it’s own component allows for better management of different versions. For example, you can group all API versions, even deprecated or refactored ones grouped together under a centralized Design. This provides you a record of the API and how it’s evolved over time.
You’re also able to scale the catalog separately from the consumption interfaces, meaning better performance and optimization.
Finally, the catalog is the location for your core API team to incorporate and ensure general API management best practices, such as good API design, robust API security, and spotting areas for improvement and greater efficiency.
The case for Multiple API Consumer Portals
When it comes to the API portal, we recommend a multi-portal approach, and tailored views within each.
Enterprises are expanding their API consumer audience to include internal, partner, and external users, as well as increasing numbers of business personas in additional to the traditional consuming developer.
One API portal doesn’t work for this evolving ecosystem; the portal can too quickly become just another view of your catalog. This results in lots of irrelevant content for each audience, making it hard for them to find and use what they’re looking for. Too much or too little detail surrounding the APIs is a problem too (think the granular view an internal developer will need vs a customer’s product owner). Gartner states this as one of the key barriers to API adoption in portals. This ultimately leads to reduced benefits and cost savings associated with API reuse.
The most common pattern we see in mature enterprises is separate API portals for each consumer audience i.e. separate internal, partner, and public portals. Supplemented by different views (powered by access control rules) for different personas within each portal, e.g. internal developers vs internal business users.
Targeted and tailored consumer experiences
A multi-portal approach ensures you can provide multiple views of APIs based on the personas that will be using them. You can customize the consumption interface for different consumer groups, as well as customizing the contents of the portals themselves.
This ensures you’re providing relevant APIs for each audience, in experiences they’ll love. Making it easier for consumers to discover, evaluate, and onboard themselves to your APIs in a self-service way.
Better experiences; better benefits for you
The multi-portal approach supports increased API adoption by enhancing user engagement and satisfaction. Not only do you gain greater efficiency through reusing your existing APIs, but you’re also helping to foster an environment of self-service innovation and collaboration.
Localized compliance
In addition to catering to different types of consumer, you can also provide tailored experiences and contents for different regional groups. This can help address regional regulatory and compliance requirements by advertising the specific API versions that are aligned to these legislations directly to the consumers who should be using them.
Separate…but integrated
While we’ve discussed why the API catalog and multiple consumer portals should be their own distinct components, it’s important to remember they must be seamlessly integrated.
You need to be maintaining consistency, control, and synchronization across all of the portals and their views as well as the catalog. Enterprises are trying to enable a small core API team to manage the API ecosystem, and in turn enable a much wider group of users across the organization to access and make use of the API inventory. It goes without saying that a separate catalog and multi-portal approach must not be adding unnecessary overhead to this core group.
The catalog acts as a backbone, acting as a best-of-breed supply chain, supplying the portals with the necessary information and updates, thereby ensuring that all parts of the system are aligned and up-to-date. This integration also supports better connections between the API provider and consumer, as well as the ability to advertise and drive demand for APIs currently in-flight (not just those already in production).
In addition, you’re able to manage and track consumption and improvement opportunities in the same place you’re tracking and using design and runtime metrics (i.e. the catalog), further improving effective business decisions to accelerate your API program maturity.
Finally, this approach lowers the pressure — and cost — of hoping you get your consumer experiences perfect on the first try. When the IP is held in your catalog and you have the ability to curate and promote the most valuable APIs, while quicky standing up new portals and tailoring the views and contents, you have true flexibility and responsiveness to support your consumers’ expectations.
Implementation considerations
Implementing multiple portals and a central catalog comes with two key considerations.
Firstly, consider how you will extend your lifecycle management process to incorporate the implications of multiple users across multiple portals consuming your APIs. You need to be able to track the lineage of these new dependencies so you can iterate and update multiple API versions without affecting production services. Robust endpoint management, policy and key management, and performance tracking and management become key here too.
The second consideration is choosing the right approach to implementation. Will you build these components, leverage open source offerings, or buy specific tooling? We believe that the true value comes from what’s in your catalog and portals, rather than the catalog and portal functionality themselves. That’s why out-of-the-box capabilities like our ignite Platform is a wise choice for enterprises, allowing you to focus more on using your APIs to deliver your digital initiatives and less on building and maintaining the underlying technology.
Example best practice architecture using digitalML’s ignite Platform
A seamless ecosystem can be visualized using ignite below. Our ignite Platform offers a Holistic Catalog for all APIs, powering tailored Consumer Portals, all kept fresh by Extended Lifecycle Management. And tied to your existing IT infrastructure like SCM repos, API gateways and runtime platforms, for one seamless framework.
Conclusion
To drive API adoption and reuse alongside effective API management, your API catalog and consumer portals need to be two distinct interfaces. Moreover, the catalog should be the singular location for your entire API inventory where a core API team can capture, manage, govern, curate, and make decisions on the portfolio. The API consumer portals should take a multi-portal approach, offering tailored experiences and contents for your varying consumer audiences to easily discover, evaluate, and onboard your best APIs in a self-service way. While distinct, the two components need to be tightly integrated, so that contents can be kept fresh and active and a unified seamless API management and adoption framework is established.
Learn more about how the ignite Platform is helping large enterprises address their complex API needs at digitalml.com.
