If your organization provides APIs, the success of those APIs depends on how well your API developer portal highlights and explains them. Current and future stakeholders will go to your API developer portal to learn everything possible about your API(s) and even your company, both from a technical standpoint and also just as importantly, from a business standpoint. How do you make sure that your developer portal is best-in-class? There are a number of facets that go into the leading API portals and ProgrammableWeb has written a series of articles to help you understand what best practices are being used by the top providers.
The initial article in this series provided a comprehensive checklist of the criteria needed to build a world-class API developer portal. Subsequent Editor’s Choice articles including this one will provide a more in-depth look at how individual API providers have executed on the various criteria.
In our checklist article, we discussed the importance of explaining the business case for your API to a decision-maker who may be learning about your API for the first time. Going beyond this, one proven method of engaging with this audience is to show example use cases that address how your APIs can solve a developer's specific problems. Carefully thought out use cases have the ability to work not only for an executive-level audience but also for visitors who work at a product level and who are hoping to understand all of the possibilities enabled by your APIs. The descriptions for the use cases do not need to be long, but they do need to focus on outcomes as opposed to listing a set of features. If a user is visiting your portal for the first time and isn’t quite sure what your API does or why they should use it, you need to be able to tell them a short story that convinces them that you understand the space well and are best positioned to help them.
We should take a moment to discuss the difference between a use case and a case study. A use case should be general in nature. It should reference how the API can help developers with their problems, and the outcomes that can be enabled by the API. It shouldn’t however be specific to one customer’s API experience. Case studies on the other hand are meant to bring customer stories to life including the challenges they were facing, the solutions they turned to, and the business outcomes (qualitative or quantitative). We have previously covered how Twilio’s case studies are best in class.
Western Union’s developer portal highlights the availability of its use cases right on its home page. Beneath a banner and a statement that makes the business case for the API is a graphic offering links to three full use cases and then two more links that cover additional use cases. In total, Western Union has seven different use cases for users to explore. The fact that Western Union has devoted this much real estate to its use cases is a signal that it understands the need to educate decision-makers about its API.
Figure 1 The Western Union developer portal landing page highlights five use cases for its API
The two ways to present use cases are to provide a summary or a bullet list on the portal home page that touches on the ways that your API can solve the problems a developer may face, or preferably, to write a more detailed narrative that resides on its own page. If you choose the second way, then you will need to give the user a clear way to find them either through links on the page or within the portal’s navigation.
Figure 2 Western Union provides a brief and to the point outcome for real-life use cases of the API along with attractive graphics.
Western Union presents each use case with a consistent, templated format. At the top of each page is a banner image, the name for the use case, and a short description. The description describes the experience that is enabled for customers through the use of the API using language that is concise and clear making it easy for decision-makers to understand the value.
Underneath the banner is more text, restating the use case if the user missed it in the banner. Below the text is one of the more unique features we have come across. Western Union has chosen to show the customer’s journey through the use of an attractive step-by-step set of graphics with accompanying text. This treatment simplifies the use case into an easy to follow workflow that could easily resemble the same business process at any other company. As a result, the use cases are brought to life in a way that we’ve rarely if ever seen.
Figure 3 Each use case is summarized with key benefits and a link to how partners were enabled by them
Each use case concludes with a summary of key benefits. Here we start to see more mention of features instead of customer outcomes but, by this point, it feels appropriate. Some of the use cases also link to a customer story with more details about how partners were enabled by the API. This is a good idea and should be standard for an API portal. Ideally, a provider should have a case study for each use case.
Use cases are an often neglected part of API developer portals. But, they can be a quick and effective way to engage with decision-makers. At a bare minimum, all portals should have a set of use cases even if they are little more than summaries. Western Union has created one of the best sets of use cases that we have come across. It has taken the time to clearly lay out the real-world scenarios enabled by its API which allows decision-makers to see how their problems are addressed. For these reasons, ProgrammableWeb would like to give an Editor’s Choice Award for excellence in Developer Experience (DX) to Western Union.