Best Practices: How to Engage Developers with a World-Class API Portal

Continued from page 1.

1. The API as the Problem Solver

Are developers the only audience interested in visiting your portal? Absolutely not. APIs have moved beyond being an IT concern, and choosing them now involves numerous organizational stakeholders. In terms of non-developers, that audience includes business executives from other organizations who are often looking for partners to help them co-create better end-to-end customer experiences.

For example, in May 2017, McDonalds started working with UberEats to enable its franchisees with a home delivery option. APIs were the ultimate enablers of the new end-to-end customer experience. But interest in co-creating that experience began at the business level. With this increased range of stakeholder types, your portal's target audience is more varied than ever and the portal's content and organization should be designed to address that diversity.

According to Brad Fults, head of Run Engineering & Connected Devices at fitness gear manufacturer Under Armour, four major categories of audience types will visit your portal: newcomers, debuggers, decision-makers, and searchers. While developers and product managers are likely to comprise the majority of users across those audiences, the decision-makers will often include a CTO or, in some cases, even the CEO. At this stage of their API discovery, the decision-makers need to understand exactly what your API does, how it fits in with their businesses, and how the API can help solve their specific problems.

Let's look at our first example of a top provider. In Figure 1 below, we see a partial screenshot of BBVA's services home page. First up is the business proposition letting decision-makers know how BBVA's APIs can be used to process payments, build a Customer Identification Program (CIP), or access deposit accounts and debit cards. This is unambiguous and at a high level and it lets decision-makers know what they can expect from BBVA's APIs. Below the header, the home page includes calls to action (CTAs) that provide more narrowly-defined unique value propositions (UVPs) for each of the individual APIs.

Figure 1: BBVA's services home page greets you with a clearly articulated UVP, which is something that's sadly missing from many API developer portals.

Figure 1: BBVA's services home page greets you with a clearly articulated unique value proposition, which is something that's sadly missing from many API developer portals.

Going one step beyond explaining the business case for an API, you also want your landing page to address how your APIs can solve a developer's specific problems. Providing use cases works well not only for an executive-level audience but also for visitors who work at a product level and who are hoping to understand all the possibilities enabled by your APIs (and which of these map to their needs). On this page, your descriptions must focus on outcomes as opposed to listing a set of features. Keith Casey, a developer, and engineer who, at the time of this paper's publication, was focused on identity and authentication with the access management company Okta, describes this content as the storytelling style of documentation. According to Casey, "A user may come to your website asking, 'I'm not 100% sure what you do or why I should use it, [so] tell me a short story. Convince me that you understand the space and you can help me.'"

Figure 2: Google presents results-oriented examples that show how using the Google Maps API can generate new business or expand your company's scope.

Figure 2: Google presents results-oriented examples that show how using the Google Maps API can generate new business or expand your company's scope.

Look at the "stories" the Google Maps API page tells us. These are everyday possibilities that show that Google understands a user's needs and how this API can meet them when in the hands of a competent developer.

Case studies (presented in text, images, video, or a combination of all three) allow developers to dive deeply into real-world customer solutions that use your APIs or SDKs (software development kits). These use cases are a wonderful way to help decision-makers understand your product's benefits and to demonstrate its trustworthiness by showing how others have used it successfully.

Facebook, another top API provider, offers a great set of case studies (or what they call "success stories") on its API portal to educate visitors who are still in a decision-making mode.

Figure 3: Facebook's API use-cases emphasize how customers like Ripl solve problems and bolster new business initiatives.

Figure 3: Facebook's API use-cases emphasize how customers like Ripl solve problems and bolster new business initiatives.

Each story describes the company's goals, the solutions used to meet those goals, offers qualitative outcomes, and the Facebook products used to achieve those outcomes.

An app gallery is another great way of showcasing how the real world is using your API. Not only are galleries aspirational by showing what's possible, but they can often double as app store-like marketplaces, thus providing developers a way market their apps and generate revenue through the usage of your API (not to mention how increased consumption of those apps increases the consumption of the API which could result in increased revenue, depending on the API's business model). Some API providers generate additional revenue for themselves by underpinning such marketplaces with revenue sharing-based business models where, in exchange for helping the app developer to market its application, the API provider gets a cut of the business.

Figure 4: GitHub does a good job of having an active marketplace that offers a wide range of apps that integrate with its service. It's one of the reasons why, what started as a small hosting resource for developers, was acquired by Microsoft in 2018 for $7.5 billion.

Figure 4: GitHub does a good job of having an active marketplace that offers a wide range of apps that integrate with its service. It's one of the reasons why, what started as a small hosting resource for developers, was acquired by Microsoft in 2018 for $7.5 billion.

Along with its marketplace, GitHub provides developers clear instructions on how to list their apps, including the specific criteria they must satisfy.

Speaking of business models and marketplaces, another critical part of clearly presenting the UVP of your API involves a description of the business models it relies on, including specific pricing information. Make sure a visitor to your portal can quickly identify and understand the costs of consuming your API, and any limitations that go along with this, such as usage limits (maximum allowable API calls over a given period of time) and rate limits (maximum frequency of API calls). Across the API economy, there are numerous API monetization models from which to pick. Some are more direct than others. In other words, whereas some API business models are driven by the number of overall API calls being made (a direct form of monetization, sometimes referred to as a "coin-operated API"), others might allow an unlimited number of API calls in exchange for a subscription to an advanced tier of service. At last count, ProgrammableWeb observed and documented over 30 different API business models in use across the API economy.

So make certain your choice is informed by your overall business strategy. For example, if you use a model that charges developers directly for API calls, consider having a free tier of service that allows a restricted number of API calls at no charge. This way potential users can benefit from trying your API in a limited capacity, thereby setting their expectations for what the API can do should they decide to engage your offerings with a more robust tier of service. Furthermore, research indicates that your API consumers are three times more likely to eventually upgrade to a paid tier if you include a free tier as the starting point.

In conducting our research for this whitepaper, we were surprised by just how difficult it is to find providers who are upfront with their pricing. Many even hide that information behind a registration wall or a link requiring you to contact their sales team.

Figure 5: While businesses want to encourage or even demand that a prospect interact with a member of the sales team as soon as possible, requiring that additional click to learn crucial information (like pricing ranges or tiers) is enough friction to halt many decision-makers' progress through the customer purchase funnel. Ease of access to pricing information along with a free tier of API access will maximize the rate of converting visitors into customers (known as the "conversion rate").

Figure 5: While businesses want to encourage or even demand that a prospect interact with a member of the sales team as soon as possible, requiring that additional click to learn crucial information (like price ranges or tiers) is enough friction to halt many decision-makers' progress through the customer purchase funnel. Ease of access to pricing information along with a free tier of API access will maximize the rate of converting visitors into customers (known as the "conversion rate").

Many others inexplicably bury this information without providing any clear road signs directing visitors to it. Of course, many APIs are free to use, only requiring that you register and get some form of an authorization credential. But even in these cases, the providers often do a poor job of communicating that the API is free.

AccuWeather, a weather media company, does a nice job by having a dedicated pricing page that's very easy to navigate to from the developer portal landing page. The basics of its pricing strategy are communicated through a table on the pricing page. In Figure 6, you can see that the pricing model has different tiers including a limited trial tier that is offered for free. This is called a freemium model and is a great way to get interested developers to try out your API with minimal investment.

Figure 6: AccuWeather's informative site assures users that the company's API pricing structure is designed to accommodate their success and growth without charging them for services they don't need or want.

Figure 6: AccuWeather's informative site assures users that the company's API pricing structure is designed to accommodate their success and growth without charging them for services they don't need or want.

As part of helping users understand both your company and its API, you also need to publish a clearly written developer or API Terms of Service that's easy to find within the portal. Too many providers only have a general Terms of Service (for their website) that either neglects to specify the terms for using the API or doesn't mention the API or platform at all. The music streaming company Spotify has published a Developer's Terms of Service that's very clear and easily found. The terms are specifically written for developers and clearly define the platform as "our developer tools accessible (e.g., APIs, SDKs, Widgets) and documentation described, on our Spotify Developer website."

Continued on page 3.

 

Comments (0)