If you’re old enough, you can probably remember the sound of the Sears or JC Penney catalog landing through the mail slot or slapping down on the kitchen table. Even if you’re too young to remember those behemoths, you might still find yourself – or your children – dog-earing page after page of holiday catalogs each fall. Well into the digital age, catalogs are an enduring medium — even Amazon sends a holiday toy catalog! Season after season, the catalogs arrive, though they show products that could be bought online any day of the week.
Much of the appeal—and value—of catalogs is in discovery. When you browse through a catalog, you are building a mental map of the product offerings from that source, getting a sense of the breadth and depth of their offerings. Even if you don’t order right away, you have gained information about the company and its products that makes it more likely you’ll think of them in the future. Retailers know the power of browsing to convert into sales – it’s why the catalogs keep coming.
Compare that with the experience of online shopping. If you have a specific need in mind, you go to a site that you know is likely to have what you require. You search for it or navigate directly to it without stopping to browse other categories. Maybe you already have a specific brand you trust, or you are looking for a direct replacement of something that broke. You navigate to the product you want pretty directly, click, and buy. There’s not much “discovery” at all, especially if you are in a hurry.
Your API consumers are a lot like online shoppers. They’re set in their ways, have probably defined their needs pretty narrowly, and aren’t really aware of the whole landscape of possibilities—and API catalogs may be just the tool you need to break through to them. By tapping into the power of browsing, you can show developers other API products they may not be aware of, suggest alternative paths, and showcase your full range of solutions. Particularly if you are in a space with tough competition, an API catalog can help you get over the hurdle of discovery.
What’s an API Catalog?
We’re glad you asked! Catalogs come in many different forms, but they share a similar purpose. A catalog organizes products or resources to make it easier to find what you need without needing to know exactly what you’re looking for. An API catalog is an interface that allows potential users to browse through available APIs grouped by functionality or other user concerns.
High-quality API catalogs have a few key features:
- They are searchable or filterableso that developers can easily narrow down the options. You’re not always trying to lead developers to a single tool—providing thoughtful filter criteria can help users define their needs while they consider multiple options. The Twilio API catalog, which is included in our list of examples below, is an especially good demonstration of this idea.
- They offer comparable, digestible detail for each API in the catalog. The catalog entry should be a snapshot, not the full product detail. But it needs to be consistent across entries so that developers can readily compare their options. The goal is to provide enough information for users to build a mental map of your API program so that they know where to go to get what they need, now and in the future.
- They offer a clear path forward, with links to high-quality documentation and “getting started” resources so that developers who find a useful tool in the catalog can then quickly implement it.
It’s also worth considering what API catalogs are not:
- They are not a stand-in for thorough documentation. You still need to provide depth and detail about how to use your APIs beyond what’s in your API catalog—this is just a first stop.
- They are not sales pitches. Unlike their mail-order equivalents, API catalogs are resources for developers who are serious about finding a practical solution and want to learn more about promising tools. They need to be factual and fluff-free if you want them to be useful.
- They are not indexes or databases. No doubt you have a list of all your APIs already available somewhere, but it is probably not organized or presented in a way that prioritizes user needs. An inventory database isn’t the same as a catalog, even though they share some data—catalogs are designed for consumers. Compare Twilio’s Github page to their API catalog. All the resources in the catalog are also available on GitHub, but if you’re shopping for a solution, you’ll find what you need much faster in the catalog.
Who’s Shopping? Public vs. Private API Catalogs
Whether you’re producing APIs for public use or building a service architecture of private and partner APIs, API catalogs can be a powerful tool. In either case, they can drive discovery and guide developers toward your preferred solutions. But considering the audience and purposes of your API catalog will help you determine what features are most important to include.
Drive Monetization of Public APIs
Most developers have had the experience of using a tool for a long time without realizing that it is part of a broader package of possible solutions. That phenomenon isn’t limited to APIs – legendarily, over 90% of feature requests for Microsoft Office products prior to 2007 were for features that already existed. Once users find a solution for their immediate problem, they tend not to be motivated to research other product features. An API catalog showcases the full range of your API products. A developer may quickly discover a more robust solution than they imagined or realize the breadth of options is greater than they thought, leading to deeper integrations and greater revenue potential.
Nielsen Norman Group suggests several strategies for encouraging users to explore further. Here are a few that API catalogs can help deliver:
- Visible features: In NNG’s words, “Don’t make people search for key features.” API catalogs are all about making options visible without requiring a search. A browsing interface encourages exploration and can lead users to entire categories of products they hadn’t considered and would never have searched for on their own.
- Visible signifiers: A grid of icons or thumbnails with some scannable text is much easier for potential users to parse than a text-based list. Visual elements can make relationships between API products clearer and indicate important features and functionality. UX that emphasizes actionable buttons over text encourages users to take actions that lead them closer to integrations.
- Just-in-time learning: An API catalog shifts implementation details to where they are needed. Overwhelming developers with information too early can be a turn-off. The most useful functionality is visible at the catalog top level, and crucial details about system requirements and compatibility are readily available, but the nitty-gritty details of documentation can be saved for later, when developers have moved beyond the browsing stage.
- Low-commitment previews: Let users see what will happen before they have to install or sign up for anything. An API catalog is a great place to showcase a quick GIF or diagram that makes functionality clear.
Internal Developers Want Efficient Solutions
If you are dealing mostly with internal, private APIs, you might think an API catalog isn’t really appropriate for your needs. It’s true that API catalogs serve different roles for private API programs than for public ones, but the basic principles and practices are similar. You don’t have to be building APIs as a revenue center to benefit from improving discoverability and highlighting best practices.
There might be no better use case for an API catalog than a large microservices architecture. Their main benefit, in this case, is efficiency, which they can deliver in multiple ways:
- Prevent redundancy by making it easier to find the path others have followed.
- Improve governance by promoting preferred tools and versions.
- Publicize time-saving tools to save resources across teams.
For internal teams, an API catalog is somewhere between a knowledge base and a repository—it is both a source of information on best practices and a tool for getting new APIs integrated into code more efficiently. A private API catalog can be more prescriptive than a public catalog: you know your internal teams’ use cases and development lifecycle. You can shape the content and format of your API catalog to guide your developers toward your preferred practices, resulting in a more consistent service architecture.
An API catalog can also reduce the burden on your DevOps teams when new product engineering teams are ramping up. The catalog allows dev teams to quickly see what tools are being used elsewhere in the organization, so that they can draw on the expertise and efforts of other teams who’ve already made the investment. For DevOps teams, a catalog is an easy way to share best practices and answer questions so that supporting engineering teams involves fewer variables.
Browse a Few API Catalogs for Ideas
If you’re considering building an API catalog, we’d encourage you to check out a few examples:
- Meta Developer Docs: Meta, formerly Facebook, offers developers a lot more APIs than you might have realized—thus demonstrating the need for API catalogs! Notice that the Meta catalog doesn’t include any search or filtering functionality on the first page—but it does have very clear categories with plenty of on-brand whitespaces around each API name, making it easy to quickly scan the options in each category.
- Twilio API Reference: Twilio offers a little more information about selected APIs on the front page than Meta does, and the company also makes it easy to filter by use case and development platform so potential users can quickly narrow down the options. For each API that comes through in your filtered results, you see a clean, informative card offering a few actionable buttons.
- Using Slack APIs: Slack doesn’t have nearly as many different APIs as Twilio or Meta, but it organizes what it does have into three tidy categories, with a bit more information on the most common ones. Slack might be able to drive discovery more by reducing the visibility of the sidebar menu when users are in this view—the “Other APIs” category has a manageable and interesting list of options but requires users to scroll down to see it, while the sidebar has a lot of information that users probably don’t need until they’ve selected one of the APIs as their entry point. However, the amount of information available on this page for each API makes it easy to decide how to proceed while also providing a glimpse of other possibilities.
- Amazon’s Selling Partner APIs: Working with Amazon is always a daunting task. The options for developers can feel overwhelming at every turn. In fact, finding your way to this page in the first place is not easy. But once developers have arrived, they find a clear, digestible catalog of all the APIs relevant for building e-commerce integrations with Amazon. If that’s your big-picture goal, this page gives you a lot of potential resources in one place without a lot of distractions. Within the Amazon ecosystem, it’s a welcome bit of simplicity and transparency, which helps build trust with developers.
We’ll be back next month with more in-depth discussions of what an API catalog can and can’t do for your API teams. In the meantime, look for those moments of discovery in your own use of APIs, developer tools, apps, and websites. What kinds of user experiences get you to look deeper and uncover new use cases and functionality in products you use?
Your API and DevOps teams build products worth promoting to the developers who can use them most effectively. Bringing your observations of what inspires discovery back to your API catalog can be a tool for making a better developer experience.
