You have a lot of choices for managing your API programs—there are more tools to consider than you have time to think about them, and the marketing emails keep coming. We know that. But we’re still going to advocate for one more tool: API catalogs.
The best reason to maintain an API catalog is actually the problem we just mentioned. The variety and scope of API tools used in modern businesses is overwhelming, and navigating all the options takes time and knowledge many of us don’t have. Just like a physical catalog, API catalogs organize information about available APIs in a way that’s optimized for discoverability.
Last month, we looked at the benefits of an API catalog and some practices for creating a good one. Maybe you’re still not convinced, though. You’ve already made investments in so many other tools—surely one of them is good enough? It’s certainly possible. But let’s take a look at what you already have and see how API catalogs stack up—we think you’ll see they still have value to add to your existing infrastructure.
If You Have a Developer Portal…
We love a good developer portal—and, obviously, so do developers. An API catalog won’t replace your developer portal, but it can be a very effective addition. As the scope of an API program grows, developer portals can start to sprawl, and users may find themselves overwhelmed by possibilities. As the number of potential paths grows, developers may struggle to find what they need. Your users may find themselves needing some additional signposts.
API catalogs can bring clarity and easy discoverability back to your developer portal. Think of them as a portal of portals, or a signpost for signposts—with simple visual organization and flexible filtering, they help developers quickly understand your API product landscape and choose a path that suits their needs.
Another way API catalogs add value to your developer portal is as a bridge between your main product page and your technical documentation. Many API companies have a great big-picture “What We Do” product guide somewhere near the top level of their developer portals. From there, developers can sometimes find themselves on their own to figure out what comes next, without enough context to navigate detailed technical reference docs. An API catalog is a high-level “How We Do It” resource, filling the gap between the occasionally vague promises of production sites and the in-the-weeds details of API references.
If You Have an API Gateway…
If you have a microservices architecture, you likely have an API gateway to coordinate authentication and access. This makes some aspects of microservices simpler, but a gateway can’t solve all the challenges you’ll face as you scale up. Onboarding anyone new can still be a slog, and even current product teams may find it difficult to stay up to speed on what tools to use and when.
API catalogs are a simple way to improve discoverability for your internal API program and to streamline the process of introducing new tools and services. Individuals and teams can more easily see what tools are available to them, and they can get a clearer understanding of how different services work together based on how they are presented in the catalog.
An added benefit of better discovery, and thus a benefit of an API catalog, is that it encourages innovation and collaboration. Presenting old information in a new way leads people to think differently, potentially uncovering new sources of value and efficiency.
If You Have a Public GitHub Repository…
We’ll take our own GitHub repositories as a starting place for this conversation. Stoplight produces a variety of open-source tools and libraries to support our API products. In a public repository, you can browse or search, and if you have an idea of what you’re looking for, you can go straight to the source. For developers who are already familiar with Stoplight or similar tools, we want to make it easy to see how everything works and let you get to work implementing and customizing.
But what if you aren’t as sure what you need, or aren’t as comfortable evaluating code on your own? An API catalog can provide developers a place to browse or search your tools, with a scope that’s manageable for someone just getting started with your products. You can present important details in a scannable format, giving users more at-a-glance information than what they can get from repository names.
An API catalog is also a more intentional format than a list of GitHub repositories, even if you’ve pinned a few key ones. You can use visual elements to show relationships between tools, highlight new versions by moving them to the top of the catalog, and allow sorting and filtering on whatever features or categories best fit your users’ needs. The listing for each API in your catalog, then, can include a link directly to the code repository.
If You Have Searchable Product Demos…
Many API companies have videos or articles to show off product functionality and use cases. These resources are terrific, but they’re often oriented toward end users, not the developers who will do the work of integrating your API into their code.
Developers often know what the use case for a tool will be ahead of time, and they are more interested in knowing what it’s like to actually build an application around your API. Product demos that focus on business functions or outcomes, like sales enablement or financial reporting, are not going to tell a developer what they really want to know: what authorization standards are accepted, what languages have SDKs available, or what rate limiting is in place, for example.
Further, many developers will be reluctant to spend much time investigating a tool that doesn’t let them kick the tires by poking around the docs on their own. An API catalog can highlight business use cases by categorizing or filtering around them so that developers can quickly find their way to the tool they’ll be using. Then, the catalog provides an easy gateway to docs, technical demos, and sample code, which will do much more to hold a dev’s interest than a product video.
Even If You’re Overwhelmed by Tools…
API catalogs are lightweight, customizable, and purpose-built. We’re not recommending them because we love tool creep. It’s more like the opposite, actually.
We know it can feel like your API tooling has taken on a life of its own and is growing out of control. Cutting through the thicket of information sometimes requires a tool that helps you impose order. An API catalog can give you and your users a better view of the whole garden of tools you’ve got growing so that you can prune away the excess and find the ones that will serve you best.
