In the spirit of treating APIs as though they are products -- something every organization should do for both their internal and external APIs -- the success or failure of those APIs depends on the comprehensiveness and digestibility of your API developer portal. Your API developer portal is where stakeholders of all types will go to learn everything possible about your API(s) and even your company. What makes for a world-class API developer portal? There are a great many facets that go into the leading API portals and ProgrammableWeb is building a series of articles to help you understand what best practices are being used by real world API providers.
This series was kicked off by a comprehensive checklist of the criteria needed to build a world-class API developer portal. This checklist was largely based on the many best practices we have observed across the API economy and the list alone is a testimony to what it means to treat an API a product. Subsequent Editors Choice articles including this one will provide a more in-depth look at how individual providers have executed on the various criteria. In some of these cases, we are looking at the overall portal while in others, we’re giving an Editors Choice for exceptional execution on specific criteria items.
One of our key criteria items has to do with the extent to which API providers explain sample use cases to which their APIs might apply. This helps visitors to understand the API’s unique value proposition compared to other APIs across the API economy. This article looks at Twilio, a communications platform provider that enables phones, VoIP, and messaging to be embedded into Web, desktop, and mobile software. Twilio’s developer portal does a fantastic job with its case studies that help educate visitors who are still in a decision-making mode.
When building your API developer portal it is important to remember that your audience is not a homogenous mixture. Developers are likely to comprise the majority of your portals visitors. But you cannot afford to forget the decision making audience that includes product managers, CTOs or in some cases, even the CEO. During the early stages of their API discovery, decision-makers need to quickly understand what your API does and how it can help their business.
An easy and effective way to present your API is through case studies. Case studies (presented in text, images, video, or a combination of all three) make clear what an API can be used for, allow decision-makers to understand your product’s benefits, and help build trust in your product. After all, a set of real-world customer success stories can be far more compelling than a list of product features.
Twilio lets visitors to its site know the importance of the case studies (called Customer Stories) by having them linked in the main navigation menu that can be seen site-wide. A nice touch is that the drop-down menu is organized by business sectors so that decision-makers can quickly find the case studies that are most applicable to them.
Figure 1: Case studies are linked from the main navigation and are organized by business sector.
The breadth of case studies is impressive; Twilio lists more than 140 from organizations large and small. One of them, the TransferWise story, highlights the many things Twilio gets right in sharing its customers’ successes. The first thing visitors see in each case study is a large headline stating the key result a business realized by using one or more of Twilio’s APIs. For TransferWise, it was 90% of its customers opting-in to push authentication as a result of integrating the Authy SDK. Each header also contains a sidebar that lists quantitative results for each integration. This not only provides the highest level overview possible while encouraging users to continue reading for more details, it also gives those users some idea of the sort of key performance indicators (KPIs) they should track in their own API implementations (whether they use Twilio or not).
Fig 2: Headers for each case study include a headline that highlights the key result as well as a list of quantitative results for each integration.
When a user scrolls below the header, they are shown a box that serves as an overview of the case study. This box includes a brief description of the company, the challenge it faced, the solution(s) to the problem and what Twilio product(s) was used to implement the solution. This box serves as yet another bite-size piece of information that is easy to digest for decision-makers that may still be scanning instead of actively reading.
Figure 3: The case study overview provides additional details in an easily digestible format.
Many, though not all of the case studies include short video interviews with the company that used Twilio. The interviews are often with some of the major stakeholders of the integration project such as a product manager or an information security officer. The videos are a very snackable two minutes in length; long enough to highlight the use cases that are enabled by using Twilio’s APIs and SDKs, while still telling the story in a more immediate way than a long narrative can.
Figure 4: The TransferWise video features the product manager and information security officer, and highlights both the use cases that were enabled and the results of the integration.
Lastly, each case study is told through a long-form narrative. Each story is a length that can be read in five to ten minutes. They provide a deeper understanding of the company, the challenges it was facing, the Twilio solutions it turned to, and the outcomes (qualitative or quantitative) the company has seen. In essence, it fleshes out the points mentioned in the overview box.
As you can see, the case studies on Twilio’s site provide up to four different ways in which a decision-maker can consume each story. These include the header that focuses on key results, the overview box that provides additional details in an easily digestible format, short videos that highlight the use cases enabled by the APIs and SDKs, and the long-form narrative that gives the most complete picture of the project.
Twilio offers the most complete set of case studies that ProgrammableWeb has seen to date. Beyond the sheer number, Twilio has gone the extra step of presenting high-quality customer stories that invite an audience to explore each one at various levels of depth. It is an effort that stands apart from most API providers and has earned Twilio a ProgrammableWeb Editors Choice award for Developer Experience.