Chapter 3. The API as a Product

Anything humans create—be it product, communication, or system—is a result of making inspiration real.

Maggie Macnab

The phrase “API as a product” (AaaP) is something we often hear when talking to companies that have built and maintained successful API programs. It’s a play on the as a Service monikers that are often used in technical circles (software as a service, platform as a service, etc.) and is usually meant to indicate an important point of view when designing, implementing, and releasing APIs: that the API is a product fully deserving of proper design thinking, prototyping, customer research, and testing, as well as long-term monitoring and maintenance. “We treat our APIs just like any other product we offer” is the common meaning of the phrase.

In this chapter, we’ll explore the AaaP approach and how you can use it to better design, deploy, and manage your APIs. As you may have gathered from Chapter 2, the AaaP approach involves understanding which decisions are critical for the success of your APIs and where within your organization those decisions should be made. It can help you think about what work needs to be centralized and what you can successfully decentralize, where enforcement and incentives are best applied, and how you can measure the impact of these decisions in order to quickly adapt your products (your APIs) when needed.

There are lots of decisions to make when creating new products for your customers. This is true whether you are creating a portable music player, a laptop computer, or a message queuing API. In each of these cases, you need to: (1) know your audience, (2) understand and solve their most pressing problems, and (3) pay attention to customers when they give you feedback on how you can improve your product. These three necessities can be encapsulated in three key lessons, which we will focus on in this chapter:

· Design thinking as a way to make sure you know your audience and understand their problems

· Customer onboarding as a way to quickly show customers how they can succeed with your product

· Developer experience as a way to manage the post-release lifecycle of your product and to gain insights for future modifications

Along the way, we’ll learn from companies like Apple about the power of design thinking and customer onboarding. We will also see how Jeff Bezos helped the Amazon Web Services (AWS) division create an implementation mandate that establishes a clear, predictable developer experience. Most companies we talk to understand the notion of AaaP, but not all of them are able to turn this understanding into tangible action. However, the organizations that have a good track record for designing and releasing successful API products have all figured out how to leverage the three key lessons we’ve just mentioned—the first of which has to do with how your teams think about the API products they are creating.

The Programmable Economy Is API-Led

APIs are the interface for enabling the programmable economy, but to do so, they must be designed in such a way that they are discoverable, scalable, and fulfill the capabilities they claim to provide to solve developers’ problems. For that, companies will need to manage their developer communities’ expectations and aspirations with the right approach. This is where developer relations come into play. It establishes the link between what each of your APIs can provide and the skilled people who will integrate them into other applications: the developers. In the following sections, we’ll explore how APIs are changing the game in the programmable economy, by providing greater reach, scalability, and ubiquity, and we’ll also look at the role of developer relations in the context of API management, advocacy, and evangelism.

To talk about the importance of APIs, we need to understand why they are so important to a business strategy. In 2011, one of the most renowned investors in Silicon Valley and the founder of Netscape, Marc Andreessen, quipped “Software is eating the world.” Before then, information technology (IT) capabilities were integrated within organizations to support the business. However, with the emergence of network and infrastructure technologies that enabled the “as-a-service model” where software could be executed from someone else’s infrastructure (SaaS, PaaS, Iaas), IT became the business, where third parties could offer self-service, automated, programmable, and traceable functionalities while allowing the business to maintain full control and maintenance. And the key that enabled these third-party organizations to deliver as-a-service capabilities to others? That’s open APIs.

These programmable interfaces enable companies and their applications to open their businesses to third parties and to grow beyond their own walls and development capabilities. There are more developers, resources, ideas, market knowledge, enthusiasm, innovation, and capital outside the organization than inside. So when it makes sense, why not open assets and capabilities to a larger number of economic and societal actors that can be involved in value creation?

Competition used to be product versus product, but this has shifted to platform versus platform and will then evolve to ecosystems versus ecosystems. APIs are the programmable interfaces that lead from one form to the other.

Price, Promotion, Product, Place → Everywhere

Classic marketing managers know the 4Ps from marketing guru Michael Porter: Price, Promotion, Product, Place are the four variables that you manage and control in a product marketing strategy. But in the digital world where APIs are eating software, to quote Andrew Bosworth, head of growth at Facebook, “It is not the best product which wins, it is the one everybody uses.”1 This is the same for your API products, which means that sometimes the experience of the product that is delivered can have more importance for the customer compared to some extra features on the product you may want to add. As such, the developer experience you give to your API users will make the competitive difference.

In a digital world where IT capabilities are delivered as a service via APIs, the goal is not to be at the right place but to be everywhere. It is not about the place you can control; it is about all the places possible, in any applications. For instance, the banking and finance industry is being disrupted by APIs that are enabling embedded finance. Paul Rohan, author and Open Banking API expert, explains that the future of banking is not “in the bank” but everywhere where banking is needed: embedded in third-party customer experiences, on real estate platforms, in wedding planning applications, in car dealer website widgets, in ecommerce websites—everywhere.2 Thanks to APIs, banks could be in every customer experience they don’t own but still able to deliver banking value propositions. In a 2020 blog post, platform thought leader and industry consultant Simon Torrance estimated that within five years, embedded finance will represent a $7.2 billion opportunity: twice the total market value of current banking and finance.3 When you are everywhere, your new reach enables you to deliver value in unprecedented and untackled places, enlarging the size of your market.

Consider how this has evolved over the last 20 years. In 2000, you had to have a website to distribute your value digitally. In 2010, you had to have a mobile application. In 2020, you need an API. Indeed, the new way to conquer the digital experience is to be integrated into other people’s websites and applications. It is no longer about controlling only one or two channels but about being integrated into as many channels as possible, where your users are. As Chris Anderson describes in his book, The Long Tail (Hachette), while the first distribution channels (web and mobile) represented a significant part of the total traffic, the long tail of all the other smallest niches and channels actually represented increasing traffic over time, which in some cases became even bigger than traditional channels. Some applications, like Salesforce or eBay, get the major part of their traffic via third-party platforms, more than via their own website or mobile applications. More than 50% of their traffic is directly from APIs. The only problem for companies is that it was too hard and too costly to address them all at once, but now with APIs, it is possible to address multiple channels with the same application programming interfaces.

Now APIs are the product of our programmable world, and we will see in the following chapter how to treat them like products, from inquisitive onboarding and initial steps to delightful developer experiences and successful integrations.

Design Thinking

One of the things that Apple is known for in product design circles is its ability to engage in design thinking. For example, when describing the work that went into Apple’s Mac OS X, one of the key software architects, Cordell Ratzlaff, said, “We focused on what we thought people would need and want, and how they would interact with their computer.”4 And this focus played out in real and tangible ways. “There were three evaluations required at the inception of a product idea: a marketing requirement document, an engineering requirement document, and a user-experience document,” explained one-time Apple vice president (and one of the people credited with founding the field of human–computer interaction design) Donald Norman.5

This attention to meeting people’s needs definitely resulted in creating viable business for Apple. A continuing string of products over multiple decades contributed to Apple’s reputation for defining new trends in technology and helped it capture greater market share more than once.

Tim Brown, CEO of the California-based design and consulting firm IDEO, defines the term design thinking as:6

A design discipline that uses the designer’s sensibility and methods to match people’s needs with what is technologically feasible and what a viable business strategy can convert into customer value and market opportunity.

There is a lot to unpack in that definition. For our purposes, we’ll focus on the ideas of “match people’s needs” and a “viable business strategy.”

Match People’s Needs

One of the key reasons to build an API at all is to solve a problem. Discovering problems to solve and deciding which problems have priority is just part of the challenge of the AaaP approach—this is the what of APIs. An even more fundamental element is knowing the who. Who are the people you are serving with this API? Correctly identifying the audience and their problem can go a long way toward ensuring you build the right product: one that works well and is used often by your target audience.

Harvard Business School’s Clayton Christensen calls this work of understanding the needs of your audience the theory of Jobs to Be Done. He says, “People don’t simply buy products or services, they ‘hire’ them to make progress in specific circumstances.”7 People (your customers) want to make progress (solve problems), and they will use (or hire) whatever products or services they find will help them do that.

SHOULD YOU APPLY AAAP TO BOTH INTERNAL AND EXTERNAL APIS?

Yes. Maybe not with the same level of investment of time and resources—we will cover that in the next section—but this is one of the lessons Jeff Bezos taught us in “The Bezos Mandate” that led Amazon to open the initially internal AWS platform for use as a revenue-generating external API. Because Amazon adopted AaaP from the start, not only was it possible (e.g., safe) to start to offer the same internal API to external users, but it was also profitable.

In most companies, the IT department is in the business of helping others (customers) solve problems. Most of the time, these customers are fellow employees within the same company (private internal developers). Sometimes the customers are important business partners or even anonymous public developers of third-party applications (external developers). Each of these developer audiences (private, partner, and public) has its own set of problems to solve and its own way of thinking about (and resolving) those problems. Design thinking encourages teams to get to know their audience before starting the process of creating APIs as a solution. We’ll explore this topic in “Knowing Your Audience”.

Viable Business Strategy

Another important part of design thinking is determining a viable business strategy for your API product. It doesn’t make sense to invest a lot of time and money in an API product that has little to no return value. Even when you do a good job of designing the right product for the right audience, you need to make sure you spend an appropriate amount of time and money and that you have a clear idea of what the payback will be when the API is up and running.

For most companies, there is only a finite amount of time, money, and energy that can be devoted to creating APIs to solve problems. That means that deciding which problems get solved is of critical importance. Sometimes we encounter companies where the APIs that were built don’t solve important business problems. Instead, they solve known problems in the IT department: things like exposing database tables or automating internal department processes. These are usually important problems to solve, but they might not be solutions that have a big impact on the day-to-day business operations or “move the needle” when it comes to meeting the company’s annual sales or product goals.

Figuring out which problems matter for the business can be tricky. It might be difficult for leadership to communicate company goals in ways that the IT department can easily understand. And even when the IT team has a grasp of what problems could make a difference to the company, the department may not have good measures and metrics to confirm their assumptions and track their progress. For these reasons, it is important to have a standardized way to communicate key business objectives and relevant performance indicators. We’ll talk more about this aspect of assessing your API’s success in “Measurements and Milestones”.

The Bezos Mandate

No matter how old or new your company is, launching a successful API program—one that will transform your company—is not a simple task. One of the most well-respected companies that worked through this process (and continues to transform itself more than a decade later) is Amazon, with its AWS platform. First created in the early 2000s, the platform is widely regarded as a brilliant master stroke executed cleanly by a savvy team of IT and business executives. Although the AWS platform has become a huge success, it was born out of an internal need: a deep frustration with the amount of time needed for Amazon’s IT programs to act upon and deliver the business team’s requests. The AWS team was too slow to act, and what they eventually created was less than adequate at both the technical (scaling) and business (product quality) level.

As current AWS CEO Andy Jassy tells it, the AWS team (along with Amazon CEO Jeff Bezos and others) spent time identifying just what it was they were good at and what it would take to design and build out a core set of shared services on an interoperable platform.8 Their plan took more than three years to develop, but in the end formed the basis for Amazon’s ability to offer its now famous infrastructure-as-a-service (IaaS) platform. This now $45 billion business ($13.5 billion profit in February 2021) happened only because of careful attention to detail and relentless iterations to improve upon the original idea. Much the same way as Apple has transformed the way consumers thought of handheld devices, AWS has transformed the way that businesses think of servers and other infrastructure.

One of the important ways in which AWS was able to change the point of view internally was through what is now known as the Bezos mandate. Steve Yegge, former senior manager of software development at Amazon, describes the mandate in his “Google Platforms Rant”.9 One of the key points in the blog post is that Bezos issued a mandate that all teams must expose their functionality through APIs and that the only way to consume other teams’ functionality must be through APIs. In other words, APIs are the only way to get things done. He also required that all APIs be designed and built as if they would be exposed outside the company boundaries. This idea that “APIs must be externalizable” was another key constraint that affected the way the APIs were designed, built, and managed.

So, design thinking is about matching the needs of your audience and committing to supporting viable business strategies when deciding which APIs are worthy of your limited resources and attention. What does that look like in real terms? How can you apply these product lessons to your API management efforts in order to express the API-as-a-product approach?

Applying Design Thinking to APIs

You can elevate your APIs from utilities to products by applying the principles of design thinking to your design and creation process. Several companies we’ve talked to in the last few years are doing just that. They have made the decision that their APIs, even the APIs that are just used within the organization, deserve the same level of care, study, and design sense as any product or service that company already provides. For many companies, this means teaching their API developers and others in the IT department the principles of design thinking directly. For others, it means creating a “bridge” between the product design teams and the API teams within the same organization. In a few organizations we’ve worked with, we’ve seen both activities at the same time: teaching design thinking to the developers and strengthening the bridge between the product teams and the developer teams.

The actual content of a design-thinking curriculum is out of scope for this book. However, most design-thinking courses provide a mix of topics like the ones we’ve already mentioned in this chapter, such as:

· Design thinking skills

· Understanding the customer

· Service/workflow design

· Prototyping and testing

· Business considerations

· Measurement and assessment

If your company already has staff dedicated to product design, they can be a great resource for teaching your developer teams how to start thinking and acting like product designers. Even if your company doesn’t have dedicated design staff, you can usually find product design classes on offer at a local college or university. Many of these institutions will offer to customize a course for delivery on-site. Finally, even if you’re a small company or just a single individual interested in the topic, you’ll be able to find online courses in design thinking.

One company we talked to (a large consumer bank) decided to create its own internal design thinking course, with the product design staff delivering the sessions to API teams at various company locations. These trainers then became important resources that the API teams could call upon when they needed advice on how to improve their API designs. The goal was not to turn all their developers and software architects into skilled designers. What they were aiming to do was simply improve the API teams’ understanding of the design process and teach them how to apply these skills to their own work.

It is important to remember that the results of design thinking are more than just improved usability or aesthetic appeal of your APIs. It can result in better understanding of the target audience (customers), a focus on creating APIs that meet viable business goals, and a more reliable process for measuring the success of the APIs into the ecosystem.

As important as design is in the overall AaaP approach, it is just the start. It is also important to pay attention to the initial customer experience once the API is released and available for use. And that’s what we’ll cover in the next section.

Customer Onboarding

Anyone who’s purchased anything from Apple in recent years knows that unboxing its products can be a memorable experience. And that is not by coincidence. For years, Apple has had a dedicated team whose only job is to focus on delivering the best “unboxing experience.”

According to Adam Lashinsky, author of Inside Apple (Business Plus), “For months, a packaging designer was holed up in this room performing the most mundane of tasks—opening boxes.”10 He continues:

Apple always wants to use the box that elicits the perfect emotional response on opening…One after another, the designer created and tested an endless series of arrows, colors, and tapes for a tiny tab designed to show the consumer where to pull back the invisible, full-bleed sticker adhered to the top of the clear iPod box. Getting it just right was this particular designer’s obsession.

And this attention to detail went well beyond just opening the box and taking out the device. Apple made sure the battery was fully charged, that customers could be “up and running” within seconds, and that the overall experience was pleasant and seamless. Apple’s product teams wanted customers to love their product from the very start: as Stefan Thomke and Barbara Feinberg wrote in a Harvard Business School case, “Helping people ‘love’ their equipment and the experience of using it animated—and continues to motivate—how Apple products were and are designed today.”11

WHEN THE API IS YOUR ONLY PRODUCT

Stripe is a successful payment service delivered via a great API that developers really love. The startup’s recent 2021 valuation was about $95 billion with fewer than 4,000 employees.12 The founders’ entire business strategy was to deliver their payment services via APIs. For this reason, they decided to invest in design thinking and the API-as-a-product approach from the very beginning. For Stripe, the API was their only product. Treating their API as a product helped them meet both their technical and business goals.

This same attention to the initial experience of product customers applies to APIs. Making it possible for developers to love them may seem a far-fetched notion, but it has long-reaching implications. If your API is difficult to understand in the beginning, developers will struggle with it, and if it takes “too long” to get started, they will just walk away in frustration. In the API world, the time it takes to “get things working” is often referred to as “Time to first Hello, World.” In the online application space this is sometimes called “Time to Wow!” (TTW).

Time to Wow!

In his article “Growth Hacking: Creating a Wow Moment,” David Skok, part of the equity investment firm Matrix Partners, describes the importance of a customer’s “Wow!” moment as a key hurdle to cross in any customer relationship: “Wow! is the moment…where your buyer suddenly sees the benefit they get from using your product, and says to themselves ‘Wow! This is great!’”13 And while Skok is talking directly to people designing and selling apps and online services to consumers, the same principles apply to people designing and deploying APIs.

A key element to the TTW approach is understanding not just the problem to solve (see “Design Thinking”) but also the time and work required to get to “Wow!” The effort it takes to reach a point where the API consumer understands how to use the API and learns that it will solve their important problems is the hurdle each and every API must cross in order to win over the consumer. Skok’s approach is to map out the steps needed to experience the “Wow!” moment and work to reduce friction and effort along the way.

For example, consider the process of using an API that returns a list of hot leads for your company’s key product, WidgetA. A typical process flow might look like this:

1. Send a login request to get an access_token.

2. Retrieve the access_token and store it.

3. Compose and send a request for the product_list using the access_token.

4. From the returned list, find the item where name="WidgetA" and get that record’s sales_lead_url.

5. Use that sales_lead_url to send a request for all the sales leads where status="hot" (using the access_token).

6. You now have a list of hot sales leads for the WidgetA product.

That’s a lot of steps, but we’ve seen workflows with many more than this. And each step along the way is an opportunity for the API consumer to make a mistake (e.g., send a malformed request) and for the API provider to return an error (e.g., a timeout for a data request). There are three possible request/response failures here (login, product_list, and sales_leads). The TTW will be limited to how long it takes a new developer to figure out the API and get it working. The longer it takes, the less likely they are to ever get their “Wow!” moment or to keep using the API.

There are a number of ways to improve the TTW for this example. First, we could adjust the design by offering a direct call to get the list of hot leads (e.g., GET /hot-leads-by-product-name?name=WidgetA). We might also spend time writing “scenario” documentation that shows new users exactly how to solve this particular problem. We could even offer a sandbox environment for testing examples like this one that allows users to skip the authentication work while they learn the API.

API PILLARS

Design, documentation, and testing are what we call API pillars. Those and others are covered in detail in Chapter 4.

Anything you can do to reduce the time it takes to get to “Wow!” will improve the API consumer’s opinion of your API and increase the chances that the API will be used by more developers both inside and outside your organization.

Onboarding for Your APIs

Just as Apple spends time on its “unboxing” experience, companies that are good at adopting the AaaP approach spend time making sure the “onboarding” experience for their APIs is as smooth and rewarding as possible. And just as Apple makes sure the battery is already charged up when you open your new mobile phone, APIs can be “fully charged” at first use, making it easy for developers to get started and make an impact within minutes of trying a new API.

Early in our work on APIs and API management, we used to tell our customers they needed to get a new user from the initial view of their API’s landing page to a live working example in about 30 minutes. Anything more than that risked losing a potential user and wasting all the time and money put into designing and deploying the API. However, after one of us completed a presentation on API onboarding, a representative of Twilio, the SMS API company, came up to us and told us they aim for an initial onboarding experience of 15 minutes or less.

Twilio’s field (SMS APIs) is notoriously fiddly and confusing. Imagine trying to design a single API that works with dozens of different SMS gateways and companies and is easy to use and understand. Not an easy task. One of the keys to achieving their 15-minute onboarding goal is the copious use of measurements and metrics in their tutorials to identify bottlenecks—points where API users “drop out”—and determine just how long it takes for them to complete the tasks.

TWILIO’S NEO MOMENT

In 2011, Twilio’s API evangelist Rob Spectre wrote a blog post relating his experiences teaching others how to use Twilio’s SMS API. He tells the story of helping a developer to use the API for the first time:14

In fifteen minutes we worked through a Twilio quickstart guide for outgoing calls and after navigating a few speedbumps, his Nokia feature handset lit up as his code executed. He looked up at me, looked back at his screen, answered his phone and heard his code say, “Hello world.”

“Whoa dude,” he said, stunned. “I just did that.”

And that is pure magic.

Spectre calls this the “Neo moment” (referring to the character Neo from the Matrix movies) and says it can be a “powerful inspiration” for developers.

Twilio has worked diligently to engineer its API and onboarding experience to maximize these inspirational moments.

So, a great onboarding experience is more than just the result of a good design process. It includes well-crafted “getting started” and other initial tutorials, and diligent tracking of API consumers’ use of these tutorials. Gathering data helps provide you with the information you need to improve the experience. Just as you design the API, you need to design the onboarding experience, too. And improving the onboarding experience means acting on the feedback (both personal and automated) you get from API users.

But the AaaP approach doesn’t stop with onboarding. Hopefully, you’ve gained a community of avid API consumers that will stick with you well past the initial introduction. That means you need to focus on the overall developer experience for your APIs. This can include signing up, filling out forms, agreeing to the terms of service, setting up their environment, getting their application credentials, downloading helper libraries, being redirected to the right “getting started” section, reading the docs: all of these steps need to be as simple and straightforward as possible. If you are in a company that requires lots of time for validation, for legal or compliance purposes, you can make the onboarding better by providing a sandbox that replicates the real API environment while users are waiting for their validation to complete. Another technique is to ask what stack the developer is using so you can send them directly to the right SDK in their preferred language. More generally, you should try to implement every tip and trick you come across to make onboarding as delightful as possible.

Developer Experience

Customer interactions with a product typically last well beyond the initial unboxing. Even though it is important to make sure the product “works right out of the box,” it is also important to keep in mind that the customer will (ideally) continue to use the product for quite a while. And, over time, customers’ expectations change. They want to try new things. They get bored with some things they loved at the beginning. They start to explore options and even come up with unique ways to use the product and its features to solve new problems not initially covered by the product release. This continuing relationship between consumer and product is typically called the user experience (UX).

Apple pays attention to this ongoing relationship, too. Tai Tran, CEO and founder of social app Blue and former Apple employee, put it this way: “Whenever there’s a question about whether we should do something or not we always come back to the question of, ‘How would this impact the customer experience?’”15 Like any good product company, Apple tells its employees that the customer is king and to pay close attention to the way they interact with Apple products. And they’re not worried about making lots of changes if that means making meaningful improvements along the way. For instance, between 1992 and 1997, Apple created more than 70 models of its Performa desktop computer (some of which were never even released to the public), each an attempt to take advantage of what it had learned from customer experience feedback on previous releases.

But probably the best example of managing the UX of its products is Apple’s approach to customer service: the Genius Bar. As Van Baker of Gartner Research says, “The Genius Bar is a real differentiator for the stores and the fact that it is free really sets the stores apart from the other offerings in the industry.”16 By offering customers a place to go with all their questions and problems, Apple illustrates the importance of the continuing relationship between customer and product.

All these UX elements—acknowledging an ongoing relationship, dedication to making small improvements, and offering easy access to support—are key to creating successful API products and experiences.

Knowing Your Audience

A big part of creating a successful AaaP is to make sure you target the right audience. That means knowing who is using your API and what problems they are trying to solve. We covered this in “Design Thinking”, and it is also an important part of the ongoing developer relationship. By focusing on the who and what of your API, you not only gain insight into what is important, but you can also think more creatively about the how of your API: what it is your API has to do in order to help your audience solve their problems.

We talked earlier in this chapter about the concept to match people’s needs when working through the design process. This same work needs to continue after your API is released. Gathering feedback, confirming your user stories, and paying close attention to how the APIs are used (or not used) is all part of the ongoing developer experience. Three important elements are:

· API discovery

· Error reporting

· API usage tracking

These three (and others) will be covered in depth in Chapter 4, so we’ll just highlight some aspects of them that are important to the overall developer experience (DX) of your AaaP strategy.

API discovery

The way internal or external developers discover your APIs and the value they provide is key in starting your relationship with them. How do developers find your APIs? Since there is no search engine for APIs yet, the discovery mechanism for APIs is often described, as Bruno Pedro, cofounder of HithHQ, used to say, as “word of mouth and a little luck.”

Of course, for external APIs, your communication will help a lot with search engine optimization (SEO), along with exhibiting at developer conferences, online content marketing, online advertising, and corporate events. However, discovery is still quite rudimentary and cannot really be planned in a way where the best always wins. You will need to develop your own influence network, and this is where word of mouth will be really powerful. When a CTO or a developer asks on forums, mailing lists, or social networks, “What is the best API to do something?” your API needs to be in the response provided by others. Next, when developers find you, they still need to understand the value your API provides. You will need to set up a developer portal that clearly describes the value of your API. For instance, Twilio used to market their SMS API using the slogan “We make your application talk.” On its first website, Stripe declared, “Payment processing. Done right.” Funnily enough, the original website was devpayments.com.

For internal APIs in large organizations, one of the challenges of the API program is, even when an appropriate API is available, developers end up creating their own APIs—sometimes many times over throughout the organization. While sometimes seen as a kind of rebellion inside the company (“They won’t use the APIs we give them!”), this explosion of duplicate functionality is more often simply evidence that developers cannot find the API they need when they need it. The API discovery is often a combination of word of mouth, asking colleagues who have this legacy knowledge, and a catalog or a developer portal. The industry calls these knowledgeable employees the API librarians as they know where the API is in the system, who the owner is, and where the docs are.

API DISCOVERY

We cover the role of this key pillar in supporting your API in “Discovery” and how the role of discovery changes in large API landscapes in “Discovery”.

Having a central catalog for your APIs can help solve this problem. Establishing an API search hub or a portal where documentation, examples, and other important information can be accessed is another good way to improve the discoverability of your existing APIs.

SEARCHING FOR APIS

At the time of the release of this book, there is no single, commonly used public search engine for APIs. One reason for this is that it is hard to index services on the web since most of them don’t expose crawlable links and they rarely include links to other dependent services. Another problem is that most of the APIs in use today are behind private firewalls and gateways, which makes them “invisible” to any publicly operated API search crawlers.

There are some open source projects and formats working to make API crawlers possible, including {API}Search, the API description format, and the Application-Level Profile Semantics (ALPS) service description format. These and others offer the possibility of a future API search engine available to all. In the meantime, individual organizations can use these standards internally to start the process of creating a searchable API landscape.

At least one company we talked to made publishing to a central discovery catalog a required step in the build pipeline. That meant the developers building an API could not actually release it into production until they’d added it to the company’s API catalog and ensured all important APIs within the organization would be findable in one location—a big step toward improving the discovery quotient of their API program.

Error reporting

Errors happen all the time. They’re part of the “landscape” of APIs. While you can use good design to try to reduce user errors and testing to try to eliminate development bugs in your own code, you will never get rid of all the errors. Instead of trying to do the impossible (eliminate all errors), a better tactic is to monitor your APIs closely so you can record and report the errors that do occur. This act of recording and reporting will give you important insight into the way your target audience is using your APIs—and that can lead to improving the developer experience.

API MONITORING

Error reporting and API usage tracking (discussed next) fall under the API pillar of monitoring. We’ll explore that API-level skill in “Monitoring”. We’ll also look at how monitoring changes as you grow your API program in “Monitoring”.

One of the challenges encountered when creating and releasing a physical product (whether it be clothing, furniture, office supplies, or something else) is that it can be difficult to see errors when they occur during use. Unless you are standing right next to the person while they use your product, you’re likely to miss details and lose out on valuable feedback. For this reason, most product companies engage in extensive prototyping and in-person monitored testing. The good news is, in the age of electronics and virtual products, you can build in error reporting and collect important feedback even after the product has been released and is in the hands of users.

You can implement error reporting at a number of key touchpoints along the way for your APIs. For example:

End-user error reporting

You can add an error-reporting feature to your application. This prompts the user for permission to send detailed information if and when an error occurs. In this way you can capture unexpected conditions on the user’s end of the transaction.

Gateway error reporting

You can add error reporting at the API router or gateway. This allows you to collect the state of the request when it first arrives “on your doorstep” and can help you discover malformed API requests or other network-related problems.

Service error reporting

You can add error reporting within the service being called by your API. This helps you discover errors in coding the service and some component-level problems, such as issues with dependencies or internal issues due to changes within your organization’s ecosystem.

Error reporting is a great way to get important feedback on how your API is being used and where problems occur. But it is only half of the tracking story. It is also important to track successful API usage.

API usage tracking

API usage tracking covers more than errors. It means tracking all requests and, eventually, analyzing the tracking information to find patterns. As we mentioned in “Viable Business Strategy”, a big reason for creating and deploying APIs is to support your business. As the well-known API evangelist Kin Lane puts it, “Understanding [how] APIs will (or won’t) assist [the] organization to better reach their audience is what the API(s) are all about.”17

The data needed to determine whether your API is helping your organization to better reach your target audience is usually expressed as OKRs (objectives and key results) and KPIs (key performance indicators). We’ll dig deeper into these in “OKRs and KPIs”, but for now it is important to recognize that in order to meet your goals, you need to know just how your APIs are doing along these lines. That means tracking not just the errors that occur, as described in the previous section, but also the successes.

For example, you’ll want to collect data on which applications are making which API calls and whether those applications are effectively meeting the needs of their users, and if they match your business goals. Tracking has the added benefit of helping you to see patterns over a wide range of users—patterns that individual users may not be able to notice. For example, you might discover that applications continue to make the same series of API calls over and over again, such as:

GET http://api.mycompany.org/customers/?last-order=90days

GET http://api.mycompany.org/promotions/?flyer=90daypromo

POST http://api.mycompany.org/mailing/

customerid=1&content="It has been more than 90 days since...."

POST http://api.mycompany.org/mailing/

customerid=2&content="It has been more than 90 days since...."

...

POST http://api.mycompany.org/mailing/

customerid=99&content="It has been more than 90 days since...."

This pattern might indicate the need for a new, more efficient way for your target audience to send out mailings to key customer groups—a single call from the application that will combine the target customer group with the selected promotional content. For example:

POST http://api.mycompany.org/bulk-mailing/

customer-filter=last-order-90days&content-flyer=90daypromo

This call creates less client/server traffic, reduces the number of possible network failures, and is easier to use for API consumers. And it was “suggested” not by a customer, but by paying attention to the API usage tracking information.

DRINK YOUR OWN CHAMPAGNE

In 2017, when coauthor Medjaoui was working as a consultant, a European national railway company decided to organize some hackathons for its developer communities: one for external developers and another for internal developers.

The external event was coordinated by the communications and product management leadership. They arranged to have the IT department produce some static data available for external use and helped the IT teams design a set of simple, task-focused APIs for accessing things like station locations and departure schedules. These were implemented quickly and viewed by the IT department as “less powerful” than its own “full-featured” internal APIs. The event went quite well.

Six months later, the IT department arranged its own hackathon using the “official” internal APIs. After a while, the hackathon organizers realized the internal developer teams had switched from using the “full-featured” internal APIs to the easier, more task-focused external APIs. And the teams were more effective and productive, too.

There are a few lessons to be learned from this experience. First, the task-focused APIs were preferred by all developers. Second, creating these “simpler” APIs did not take much time or resources. Third, it is always best for IT departments to pay attention to which APIs are popular and used more often. A last lesson can be summed up by the common phrase “Drinking your own champagne” (some say “Eating your own dog food,” too). With APIs, as with any other product, it is often best for internal teams to be using the same product external teams are using.

This leads us to one more important area of developer experience (DX): making it safe and easy for developers to “do the right thing” with your API.

Making It Safe and Easy

Along with facilitating straightforward API discovery and accurate tracking of both errors and general API usage, it is important to provide easy access to ongoing support and training to your API consumers. In fact, it is the experience that occurs after you’ve successfully onboarded the developers consuming your APIs that will ensure a long-term positive relationship. We saw an example of this kind of attention to the ongoing relationship earlier in this section, with Apple’s use of the Genius Bar as a source of support for existing customers. Your APIs need their own Genius Bar, too.

Another important aspect of support for developers is making your product safe for use. In other words, it should be somewhat difficult to misuse the product in ways that result in some sort of harm. For example, it should be hard to delete important data, remove the only admin account, and so forth. Paying attention to how your API consumers (that is, developers) use the product can help you identify areas where some added safety efforts can pay off.

It takes a mix of both these elements—ease and safety—to create a powerful and ongoing connection with the developers consuming your APIs.

Making APIs safe to use

There are a number of elements of an API that can represent risk from the developer’s point of view. Sometimes certain API calls can do dangerous things, like deleting all customer records or changing all service prices to zero. Sometimes even connecting to an API server can represent some risk. For example, setting up a connection string to a data API might make it too easy to expose usernames and passwords in URLs or unencrypted message bodies. We’ve seen lots of these types of safety issues in our reviews of APIs.

Often risks can be designed out of the API. That is, you can make changes in the design that make encountering a particular risk less likely. For example, you can design an API that deletes critical data to also support an “undo” API call. That way, if someone mistakenly deletes important data, they can also invoke the undo call to reverse it. Or you can require elevated access rights to execute certain operations, such as requiring an extra data field (such as a passcode) to be sent with calls that update critical information.

However, sometimes it can be difficult to mitigate the risk through API design elements. There may be some cases where executing an API call is simply inherently risky. Any API call that deletes data is risky, no matter how many design changes you make to it. Some API calls might always take a long time to execute, possibly consuming lots of server-side resources. Other APIs might execute quickly and result in quite a lot of data in return. For example, a filter query might potentially return hundreds of thousands of records.

In cases where API calls represent unavoidable risk, you can reduce negative impacts by adding warnings to the API documentation itself. In this way, you can make it easier for API consumers to recognize potential dangers ahead of time and possibly avoid making critical mistakes. There are lots of ways you can format documentation to help point out possible dangers. Highlighted text telling the user of the problem (“Warning: This API call may return over a million records, depending on your filter settings”) is one way to do it. Another way to warn API users is to adopt a kind of labeling method using symbols. This way, there is no need to add lots of text to your documentation: readers can just recognize the warning label instead.

Physical products use information and warning symbols quite often (see Figure 3-1).

Figure 3-1. Examples of household product labels

You can adopt a similar approach for your APIs, too (see Figure 3-2).

Figure 3-2. Examples of API labels

Easy-to-read warning symbols combined with design changes to make it more unlikely for API users to make regrettable mistakes are good practices for increasing the safety of your API product.

Making APIs easy to use

It is also important to make your API relatively easy to use for your API consumers. If it takes too many steps to accomplish a task, if the names and numbers of arguments API developers need to pass are confusing or complicated, or if the names of the API calls themselves don’t make much sense to consumers, your API can run into problems. Not only will developers be unhappy using your API, but they might make more errors, too.

You can design in ease of use by adopting naming patterns that fit your developers’ Jobs-to-Be-Done vocabulary. This goes back to understanding your audience (“Match People’s Needs”) and solving their problems (“Viable Business Strategy”). But even when you do that, if your API is large (e.g., lots of URLs or actions) or just plain complicated (lots of options to deal with), you can’t always rely on design to solve your problem. Instead, you may need to make it easier for API consumers to ask the right questions and find appropriate answers. Your API needs a kind of “Genius Bar” for developers.

Probably the easiest way to provide your developers an API Genius Bar is through the documentation. By adding more than simple reference documentation (e.g., API name, methods, arguments, and return values), you can elevate your API docs to “genius” level. For example, you can add a Frequently Asked Questions (FAQ) section where you provide answers (or pointers) to the most common consumer questions. You can expand your FAQ support by adding a “How Do I…?” section that gives short step-by-step examples on how to accomplish common tasks. You can even provide fully functional examples that developers can use as starter material for their own projects.

DOCUMENTATION

We’ll talk more about this API skill of documentation in “Documentation” and discuss how your needs in this area may change as your API landscape grows in “Documentation”.

The next level up from enhanced documentation is an active online support form or chat channel. Support forums provide an ongoing conversation space where developers can ask questions to a larger group and share solutions. In the case of large API communities, these forums can even become a source of important bug fixes and feature requests. Forums can also become a valuable repository of knowledge accumulated over time, especially when you have a robust search mechanism.

Chat channels offer an even more immediate means of providing Genius Bar support for your API consumers. Chats often happen in real time and can add an additional level of personalization to your developer experience. This is also another great place to leverage and grow community knowledge about your API product.

Finally, for large API communities and/or large organizations, it can make sense to provide in-person support for your product in the form of API evangelists, trainers, or troubleshooters. Your company can arrange meetups or hack events where API users come together to work on projects or test new features. This works whether your primary API community is internal (e.g., company employees) or external (e.g., partners or public API users). The more personal you can make your connection to your developers, the more likely you are to be able to learn from them and improve the ease of use of your API.

Taking the time to make your APIs safer to use and easy to work with can go a long way toward establishing a positive relationship with your API consumers and, in turn, improving your overall developer experience.

Why Are Developers So Important in the API Economy?

How does your product evolve into a platform and, subsequently, an ecosystem? By making people work and invest in your product, instead of you working for them or investing your money and development efforts on their product. This is where APIs are a key element of value accumulation. By lowering the cost of leveraging the value that your solution provides, you incentivize people and companies to spend the time and funds to integrate your API. Instead of integrating with everybody, everybody will integrate with you, and that is a unique way to accumulate value over time. When Apple reached one million applications, those were one million applications that Apple did not have to build, which span thousands of market niches that Apple could not address due to the sheer quantity and because Apple can’t hire all the necessary product managers to analyze all the market needs. By accumulating the work and the investment of others, you transform your products into platforms and ecosystems.

Readers living in Silicon Valley may remember the Twilio advertisement with ad panels on the 101 Highway and in the main streets of San Francisco, in full Twilio-red background stating, “Ask Your Developer.” Twilio has been one of the first API companies to push really hard on developer evangelism because they knew before others that the doers of the programmable economy will soon be the angular stone of the corporate adoption of APIs. They understood that whether a decision maker or prescriber, the developer is a key influencer in an application economy.

By having the skills to develop applications, developers are a central stakeholder for an API strategy. Every integration and every application will pass through the hands of developers. In a marketplace strategy, they will be the first to use your API and the first to build applications on your platform. Developers will show the path to follow to other developers and help you benefit from marketplace traction. Internally in bigger corporations, they will be your internal API champions and will recommend the use of an API over another because they know it better and because it is safer to use, better designed, and/or better documented compared to another. In that context, we are shifting from business to consumer (B2C) and business to business (B2B) to business to developer (B2D) models.

In other words, in the 21st century, APIs are the new goods: the new products created and stored in servers, distributed on information highways through the network, transported by developers into applications, and promoted in digital supermarkets (aka application stores), where end users will come to download (for an app) or consume APIs.

For AaaPs to enable programmable business models and accumulate value at integration scale, a team must be dedicated to support that integration growth, always listening to the needs of developers and delivering them the best experience possible, both on the technical side and the human side of IT. That is the overall role of developer relations for APIs. As a result, some in the industry argue that in the programmable economy where every company will provide core competencies to others via APIs and consume core competencies of others via APIs, the role of developer relations will be more and more important, to the point that all companies will need to have a developer relations department, like they have a marketing department.

Developer Relations for APIs as a Product

As coauthor Medjaoui wrote in the third edition of Developer Marketing and Relations: The Essential Guide, there is a clear and important relationship between API strategies and developer engagement, internally or externally. It consists of understanding the relationship between community, code, and content; understanding the difference between AaaPs and product APIs; and also adopting the right metrics to measure developer engagement by developers. Finally, it is important to also spend some time discussing internal or external API monetization strategies. We will address all of these in this section.

Community, code, content

The role of developer relations when talking about APIs should be built around three blocks that the SendGrid developer relations team used to call the three Cs: community, code, and content.

Developer relations is firstly about the community. As long as humans still integrate APIs, at least until machines can do it for us, the concept of a community will remain an important part of developer relations. Being where developers are, engaging with them, listening to their feedback and ideas, inspiring them, and putting a face on the API are all part of the community’s mission in developer relations.

The community aspect is important as a soft-power to enable more word of mouth. As Tim Falls from SendGrid used to say, “A personal connection is worth more than a click,” and sometimes he found that developers were recommending the use of SendGrid even if they had never used it, because they knew the SendGrid team was caring.

Community is also about attending developer events or API conferences to keep in contact with the community, and participating in speaking engagements that are not directly involved with what your API does. Sometimes topics might be about a cool hack someone made thanks to your API, an open source package released for the community, or sometimes even more societal topics.

The second block is code. Integrating APIs is about code, and a developer’s job is to produce code that delivers value. If they can leverage code that is already provided, they can focus on implementing the business logic faster. Then, the role of the developer relations team is to provide this as code samples, SDKs, prototype applications, or API definitions (specifications) that developers will be able to use directly. Code, to the members of the developer relations team, also means writing code themselves to maintain the developer platform and the API, with a nice developer experience that we will talk more about in a subsequent section.

The third block is content. Developers love transparent and honest communications and useful content. Content is one of the best ways to attract developers and maintain them as a loyal audience of your blog and ecosystem.

Content exists in many different forms. It can be just a technical update about recent changes, it can be a blog or email about a cool customer use case, it can be more of an engineering post about a specific way to build some features, or it can be a best practice explained in detail. It can also be broader, like the recent Stripe booklet and blog post series about how to make a company and its applications carbon neutral. Content is the important part of your relationship with developers that makes your company and its APIs discoverable through SEO or social media sharing.

In summary, community, code, and content are the three pillars of developer relations that you should strive to fulfill.

AaaPs versus product APIs

There is a clear distinction to make when talking about developer relations and APIs. You need to consider whether your API is the product or if your API feeds and supports a product. You can then categorize it as either an AaaP or a product API, respectively. For instance, Stripe, Twilio, Mailjet, and Avalara are all AaaPs. They offer standalone capabilities for a specific purpose such as payments, SMS, email, and tax validation.

On the other hand, Salesforce APIs, Facebook APIs, eBay APIs, YouTube APIs, and Twitter APIs are product APIs, or said differently, APIs for a product. They exist to support and customize an existing platform. They often represent more than 50% of the total traffic to the platform and product, a considerable chunk. As much as they are critical for the business, they are often free to use because their use increases the value of the underlying business.

The role of developer relations is different for AaaPs and product APIs.

For AaaPs, the end goal of developer relations is to evangelize, advocate, and build relations that will directly augment the top-line business with the consumption of the API. As APIs are the product to be integrated and sold, the goal will be to maximize the number of valuable integrations according to the business model. In the case where developers are not the decision makers but just the prescribers, the goal of developer relations will be to have developers trained and acculturated about the benefits of the APIs. They can propose it inside their organization at an enterprise level, leading to enterprise integrations and the high revenues that follow.

On the other hand, developer relations for product APIs are mostly to inspire developers to build applications that will directly augment the value of the platform but not necessarily its direct revenues. When Facebook opened its platform APIs, it was free of charge for developers to build applications or games, and the rich portfolio of applications that resulted demonstrated that the Facebook platform was here to stay, always aggregating more application from developers.

In the end, users will stay not only because of the social network but for the full ecosystem of applications that is around it and powers it. This is similar for the Salesforce AppExchange, which has more than 5,000 business applications in 2021. In that context, Salesforce is not just customer relationship management (CRM) software anymore, but a full ecosystem of business applications powered by and around a CRM that fits many use cases across many industries. For product APIs, the role of developer relations is to nurture that ecosystem; this then scales the value and sales of the product among end users.

The story of Twitter API versus Slack API

Aligning KPIs with APIs is important and can completely change the future of the platform you are building. As Jason Costa from GGV Capital said in his article, “A Tale of 2 API Platforms,” both Twitter and Slack had great developer traction because of their important user base and their openness to build valuable applications.18 Twitter finally decided that its business model was not based on being a monetized application ecosystem but was to be a media platform making revenue through advertising. With this clearer identity, all the previous APIs published suddenly represented the complete opposite mindset of the platform, and this was the reason why Twitter highly restricted its API to third parties, hurting its developer ecosystem. Years later, it worked hard to rebuild relationships with developers, with a manifesto from Jack Dorsey himself, and hiring great developer advocates like Romain Huet, but trust in using the APIs by developers never completely recovered.

On the other hand, the Slack model was based on making an application ecosystem to enrich the value of the main Slack product. More business applications increased the value of the Slack communication platform, so the business KPIs were aligned with the APIs. To this day, the Slack API has never suffered from tensions within the developer community, which partly explains why developers love building bots on Slack. These two stories are the perfect reflection of how aligning your KPIs with APIs, and then your APIs with your KPIs, makes the difference for how you manage your developer relations strategy and APIs in the long term.

The DevRel ROI cheat sheet: Tracking success in developer relations

Evaluating the quality and potential of your developer community is a key element of your developer relations strategy. Many companies have tried to develop an internal tool to better understand their developer community. Many API management vendors have built what they call internally developer relation management software, like a CRM solution but for developers. This offers a way to better communicate, track, and differentiate developers with the most potential ROI, based on your API strategy goals, which could include reach, application ecosystem, or revenues. Also, identifying and engaging developers who are on your platform is a way to reactivate them and reinspire them to build with your API.

For that, you will need what Mike Swift, founder and CEO of Major League Hacking, calls “the nuts and bolts” of developer relations. It is a mix between developer relations practices and metrics to invest and track effectively. It is split into two parts: the API usage tracking and the developer tracking.

“If you can’t measure it, you can’t improve it,” Admiral Lord Nelson used to say. On the other side, as the Goodhart law states, “When a measure becomes a target, it ceases to be a good measure.” How do you find the right balance between metrics and the goals of your developer relations strategy? You just have to match your APIs with your KPIs.

There are all sorts of KPIs for APIs, and we have provided some here to help you get started. To get the most from each, you should couple them with the Pirate Funnel inspired by Dave McCLure, founder of famous startup accelerator 500 Startups, better known as the AARRR model: awareness, acquisition, activation, retention, revenue, and referrals.19

API awareness

API awareness is the metric that tells us how people are becoming aware of your API—how they discover your product:

Number of visits to the developer portal’s home page and API docs

There are many ways, both paid and organic, to attract developers to your home page. To attract developers to use your API, first they need to discover your value proposition and the capabilities you offer. Attracting the maximum number of developers is your main awareness metric.

Number of blog articles views and reads

Content is key in a developer relations strategy, so everything you publish must be tracked. Be sure to always put a link to the page of your developer portal that can track referrals from your articles, and monitor your engagement analytics.

Number of developers registered to written communication channels

Ask readers to register to your newsletter to get notified about new articles and API updates. This number is a key element to track how many community members want to keep receiving news from you and to compare it with the current developers registered to the API.

Number of public speaking engagements

Awareness comes from offline discussions and in real life (IRL) events. Conferences, meetups, and all public or private events where you can raise awareness of your API are important to activate a key element that is not measurable but that works well: word of mouth. This also serves as the foundation for kickstarting the viral referral phase, something that we will talk about later. For that, you can track the number of talks, the average audience size, and so on, to calculate audience reach. Also, if you have a booth at an event, you can add in the number of people you had interactions with.

Open source stars and contributions for API tooling

Providing useful tools or releasing valuable software under an open source license can deliver a lot of awareness for your company and API. This recently provided developer success to Strapi, which released a tool to build an API-driven CMS with GraphQL, and Hugging Face API, which released its natural language processing technology as open source. Through open source, these companies attracted developers, scaled their businesses, and raised a lot of money from investors—$10 million and $15 million, respectively—based on the success of developer relations in managing the developer community around the open source project of the company.

API acquisition

API acquisition is the metric that tells us how developers are engaging in our API onboarding process:

Number of registered developers

An important acquisition metric is the number of registered developers. But it is useful only at the start! Don’t depend on it as an important metric in the long term because it loses potency when the maturity of your developer relations program evolves. This metric enables you to know if there is a match between the developer community and the perceived value of the API you provide and its associated capabilities.

Number of applications and applications/developer

Most of the time, one developer account is linked to one application, but when you gain popularity or, for instance, when your API has an intrinsic value that can be reused in other applications easily (i.e., it’s a transactional or Business-Process-as-a-Service API), you will see two or more applications per developer account. That is important to track because these developers are probably your best word-of-mouth ambassadors since they understand the value of your product enough to reuse it multiple times. Tracking the total number of applications and the median of developers who have at least two applications can be a good metric in the acquisition phase.

Number of total API calls

In the beginning, the total number of API calls can be a good metric, enabling your API developer relations team to focus on increasing the use of the API and being innovative in their marketing strategy. The developer relations team will focus on inspiring developers into different usages, according to different common use cases. It should be tracked because it ceases to be a good metric really fast, unless your strategy and/or business model is attached to a number of API calls, for instance, affiliation, pay-as-you go, or indirect models like advertisement of third-party pages.

Number of third-party integrations onto other platforms

Another way to scale the reach and acquisition of your developer relations is to work with existing companies that already have developer communities and build a plug-in, add-on, or integration on their marketplace to scale. For instance, Typeform, a platform to make survey forms with an API, was based on integrating a use case into third-party marketplaces to leverage their existing developer communities. Now that it has grown, Typeform can attract applications on its platform and reverse the API integration scheme of “I spend time and money to integrate with you” into “You spend time and money to integrate with me.”

API activation

The API activation metrics help us understand the level of engagement our APIs are generating, especially early in the onboarding lifecycle:

Time to first Hello World (TTFHW)

An important conversion metric is how to transition an interested developer into an active developer. For that, you need to track the TTFHW, which is the time between when a developer registers on your platform to when they successfully invoke your API. As Twilio developer relations suggest, no more than 15 minutes is the perfect DX timing to enable developers to be successful with your API. Of course, not all internal validations and processes are possible in every organization to reach that sort of time, but reducing it to its minimum will have a direct impact on your developer activation ratio.

Number of active applications/developers

You already track the number of applications and developers as we saw earlier, but identifying the difference between developers, who are just using your API for small projects and your power developers who are integrating it into business projects can help you identify where to invest more resources, or when you need to be more reactive to a support ticket, for instance. The limit between the two needs to be defined by the API product manager, but it is important to track in order to understand the difference. This difference will also help you to define your pricing plans and help you put fair limits on your free plan, where developers have sufficiently grown their applications to become “activated” as a customer.

API retention

The API retention metrics tell us how we are doing in maintining an acrtive relationship with the develoipers we have already onboarded:

Number of “valuable” applications

As for the difference between acquired and activated, the difference between activated and valuable needs to be defined by the API product manager, according to the API strategy. A valuable application can be an application that provides lots of visibility into your application ecosystem, an application that attracts lots of users, or one that generates significant and growing revenues.

Number of active end-user tokens

A more specific metric in the retention phase is to track the retention of end-user tokens as the users of your API consumer applications. Applications that tend to grow their user base have less tendency to change their stack and switch API providers to focus on customers. This is why companies like Stripe can still charge high fees for their APIs, because payment capability is probably the last thing you want to change when you are growing. This metric can be really useful if you target an application ecosystem for your strategy like the Facebook and Slack APIs do.

API revenue

The API revenue metric lets us track the actual revenue generated by the developer activity on our APIs:

Direct revenues generated by the API

This kind of metric is pretty straightforward if your business model is directly attached to payment. Tracking revenues can also help influence an organization’s internal decision makers and C-level staff on the need to continue investment in developer relations to monetize the API.

Indirect revenues generated by the API

This metric is harder to define because it requires a subjective approach, but the exercise to link indirect API metrics with business KPIs will encourage internal support for developer relations. Developer relations pays off in the mid and long term, so some managers may want to demonstrate faster rewards internally to executives. Giving them a vision about the value created by developer relations, by translating API metrics into business KPIs, even indirectly, can help the developer relations team to continue to get support. For instance, if your API enables your application ecosystem to grow and this ecosystem increases the valuation of the company by 100% to investors and to the market, the value of developer relations needs to be linked to the market cap of the company.

API referrals

With referrals, the idea is to leverage your existing happy API users as ambassadors who foster interest in using your APIs among their networks. Here is a set of metrics to analyze that:

Conversation activity

Conversation activity is important to monitor because your developer relations team can engage developers and product managers who are actually discussing or debating “What is the best API for that?” or where to find capabilities and business processes that have been encapsulated by an API. These discussions can happen where developers are, such as on Discourse, Twitter, Medium, Hacker News, Reddit, and public Slack forums.

Mentions from others

You can source speakers and developers who are referencing your API and its value in their talks or articles and transform them into ambassadors. For that, you must track these mentions, either in conferences or developer blogs, and begin to engage them. This is what companies like Auth0 did with its ambassador program, or Docker with its Docker Captain program, which identified its best community advocates.

API presence and use in cool hacks and at hackathons

You can only track this manually, by monitoring social networks or mentions and search engine alerts, but knowing that your API is being used by others, where it happens, and who is doing it are all an important part of your developer relations strategy. Your goal is to be sure they reach out to you next time, before they actually start making their cool tool.

FUNDING API CONSUMERS WITH CAPITAL

An original strategy currently in place is to create an investment fund for API consumers and developers. This strategy has been used by major API-driven companies in the ecosystem like Mailchimp, Twilio, SendGrid, Slack, and Stripe. At some point, they all created investment funds especially for developer companies using their APIs. With that fund, they can directly take ownership of a stake in their API consumer companies and align their interest with their application ecosystem. This has many benefits, but mainly it offers the potential for developers to profit from building on your platform. Even if the number of investments per year is low, it enables you to keep developers loyal to your platform instead of your competitors by showing a path to monetization and/or funding.

In another venture-friendly strategy, Salesforce encouraged developers to build on their Salesforce AppExchange over iOS because the average revenue for an app on AppExchange at the time was $450,000, instead of $3,000 for an app on iOS at the time (2015). Even a bank in France, Credit Agricole, proposed that developers be paid based on the traction of their app, with a monthly revenue based on active users of their applications using their public APIs.

API-as-a-Product Monetization and Pricing

Lots of companies want to monetize APIs, to generate revenue, and to demonstrate value for customers and the ecosystem. It is often hard to maximize value retention and at the same time spread and expand traction through the ecosystem. We help you define all the different variables in an AaaP monetization and pricing strategy.

Infrastructure pricing versus SaaS pricing for APIs

An API represents access to your capabilities as a service. But you will have to position yourself around how you want customers to rely on you, and your mindset around how you want to deliver these APIs. Two main patterns are present in the industry: the infrastructure mindset and the SaaS mindset.

An infrastructure mindset often sets the same pricing for the same service, without a gatekeeper, as we see with Amazon Web Services and other cloud vendors. The pricing is always public, matched with usage, and not correlated with the value the user creates. Whether you can generate $1 or $1 million with an Amazon Bucket, the pricing is the same. At the scale they operate, the AWS product team cannot differentiate all the customers, so the pricing is open, transparent, and matched with usage levels.

With a SaaS mindset, you may try to design different tiers of API customers matched to the potential value expected to be generated, always trying to capture the maximum value whenever possible. For instance, when a user jumps from a few thousand API calls per day to tens of thousands, it may seem that they are now in production (and have a viable business of their own with their own paying customer base), so they can pay a lot more than when just starting out and testing their product in the market. Or when they require a service level agreement (SLA), that can indicate that this is “money” time for them, and you can make them pay a lot more for the same access to your capabilities (with penalties if you don’t maintain service performance and therefore impact their business value chain). Some companies even use API management to decide the threshold for selecting API consumer pricing tiers. They look at the median number of API calls for production users and then set the enterprise pricing plan around that level. This matches the price with the transition from testing to production and seeks to capture the maximum value the APIs can create for consumers.

You will have to decide on the trade-off between rentability and user acquisition. If your customers have a flywheel effect that increases the value of the ecosystem, you may choose to simplify the revenue model to maximize adoption instead of direct and short-term revenues. For instance, the Facebook business model is based on usage with ads, so the Facebook API needs to maximize third-party applications that encourage users to spend more time on Facebook. The API is free (up to 100 million requests per day). We have gathered a list of API pricing dimensions to consider when applying pricing for APIs.

Freshness: old versus new

If the API gives access to resources that get old and obsolete with time (like company information data), you can set tiered pricing dependent on the freshness of the data. Some financial APIs give you access for free for one-day-old data, but fresh data access needs to be paid.

Precision: blurry versus accurate

If the API gives access to resources that have different levels of value at different levels of precision, you can apply tiered pricing dependent on the level of precision. A weather prediction API can set a low price point for a one-day prediction but set access to three-to-five-day predictions at a larger price point. A credit score API could give a precise credit score for a higher fee but a generalized (blurry) representation of that score (for example, by applying a traffic light red, amber, green scoring) for a smaller fee.

Consumability: transactional versus process

Do you provide granular APIs that the customers integrate one by one and pay individually for a small fee, or do you gather complex business processes and encapsulate them into one API that you sell at a high price? For instance, the Checkr API does a background check in one API call that helps companies like Netflix answer one question: can we hire that person? The Checkr API gathers many API calls from different public services and legal sources and produces a result that is of higher value to API consumers than them making and assembling all the different API calls themselves.

Scope: reduced versus all

The API can give access to all your internal resources or to a smaller suite of functionalities. The tiered API pricing can then be based on how you define the scope of the API access. This could be per year, per geographic region, per datatype…you decide, as long as you know your customers well and understand what they really value in your proposition.

Quantity: few versus many

Another way to tier API plans is to decide the quantity of data or the number of requests allowed. The more API calls you want to make, the more you pay. Some businesses rely heavily on data when they deal with important customers, so if you know the quantity of data they need, you can set the pricing tier at volume levels.

Performance: fast versus slow

SLAs are an important part of the delivery value of an API. Guaranteeing fast and reliable access versus not guaranteeing it can be a strong differentiator for API pricing plans.

Maintenance: managed versus delegated

APIs need to be maintained across versions. Lots of companies version APIs to make them evolve over time. API consumers need to maintain their applications and update them with the new version. By making companies pay to maintain older versions, you can set different level of maintenance fees for the APIs.

Support: full versus limited

Supporting API customers can also be a differential factor for tiering API plans. Some customers are willing to pay fees for the stability of 24/7, multiregional, and guaranteed responses within an hour or less for API technical issues. This can be monetized at a higher price. For lower pricing points, or free plans, support can be offered via redirecting customers to the public forums or by providing support only via email.

License: all rights reserved versus open

Your API may give access to resources that may not be available for all uses. You can limit the potential uses of the API for low-paying customers and open greater access for higher-paying API customers.

Branding: white label versus “powered by”

Some API providers prefer adoption and awareness among developer communities over smaller revenue amounts as they are keen to keep the focus on targeting big enterprises. One solution is to give access to your API for free or at a really low price point with accreditation requirements to provide a mention such as “Service provided by…” in their products and applications. Customers could pay a higher amount to remove this obligation to label their use. Some scoring companies oblige you to mention in any online or mobile publications where the score comes from and forbid you to create a new score that includes their scoring algorithm as a variable, unless you pay a premium plan for white labeling.

Of course, there are other variables that can be applied to set API pricing strategies, but these are the most common ones.

It is important to know that the API and the as-a-service economy favor simple pricing and business models for adoption. Complex models that try to capture maximum value are less self-service and need more sales support to acquire customers than flat, open, and transparent pricing that enables easier self-service onboarding and that give a better estimation of the final price, even if they capture less value per customer on average.

Summary

In this chapter, we introduced the AaaP approach and discussed how you can use it to better design, deploy, and manage your APIs. Adopting this approach means knowing your audience, understanding and solving their problems, and acting on API users’ feedback.

The three key concepts we explored in the AaaP space were:

· Using design thinking to make sure you know your audience and understand their problems

· Focusing on customer onboarding as a way to quickly show customers how they can succeed with your product

· Investing in providing a developer experience that manages the post-release lifecycle of your product and gains insights for future modifications

Along the way, we learned how dedication to AaaP principles helped companies like Apple, Amazon, Twilio, and others build not just successful products but also loyal customers. And, regardless of whether your API program is targeting only internal users or both internal and external developers, a loyal user community is critical to the long-term health and success of your APIs.

Now that you have a grasp of the foundational principles of AaaP, we can turn to that common set of skills that we find all successful API programs use to nurture and grow. We call these the “API pillars,” and that’s what we’ll cover in the next chapter.

1 Brian Balfour, “Growth Wins,” Reforge (blog post), last modified July 25, 2018, https://oreil.ly/UJDIU.

2 Paul Rohan, “Driving Business Growth and Brand Strategy in the Api-Powered Age of Assistance," APIdays London, 2019, https://oreil.ly/IcxbV.

3 Simon Torrance, “Embedded Finance: A Game-Changing Opportunity For Incumbents,” August 10, 2020, https://oreil.ly/L6I3n.

4 Scott Meade, “Steve Jobs: Mac OS, Designed by a Bunch of Amateurs,” Synap Software, LLC (blog), June 16, 2007, https://oreil.ly/jRURa.

5 Daniel Turner, “The Secret of Apple Design,” MIT Technology Review, May 1, 2007, https://oreil.ly/ehrgv.

6 Tim Brown, “Design Thinking,” Harvard Business Review, June 2008, https://oreil.ly/VRA7Y.

7 “Jobs to Be Done,” Christiansen Institute, last modified October 13, 2017, https://oreil.ly/l1s63.

8 Ron Miller, “How AWS Came to Be,” TechCrunch, July 2, 2016, https://oreil.ly/OtRyN.

9 “Stevey’s Google Platforms Rant,” GitHub Gist, October 11, 2011, https://oreil.ly/jxohc.

10 Jamie Condliffe, “Apple’s Packaging Is So Good Because It Employs a Dedicated Box Opener,” Gizmodo, January 25, 2012, https://oreil.ly/JrY6S.

11 Stefan H. Thomke and Barbara Feinberg, “Design Thinking and Innovation at Apple,” revised May 2012, https://oreil.ly/wY4IA.

12 Ingrid Lunden, “Stripe Closes $600M Round at a $95B Valuation,” TechCrunch, March 14, 2021, https://oreil.ly/60fbh.

13 David Skok, “Growth Hacking: Creating a Wow Moment,” For Entreprenuers (blog), 2013, https://oreil.ly/YyVlI.

14 Rob Spectre, “Introducing Rob Spectre, An Evangelist With A Story To Tell,” Twilio (blog), September 15, 2011, https://oreil.ly/daUWP.

15 Shana Lebowitz, “Apple Employees Take on Any Projects That Will Improve User Experience,” Business Insider, July 5, 2018, https://read.bi/2JbmgDb.

16 Conner Forrest, “Decoding the Genius Bar: A Former Employee Shares Insider Secrets for Getting Help at the Apple Store,” TechRepublic, April 3, 2014, https://tek.io/2ykZrJl.

17 Kin Lane, “Your API Should Reflect A Business Objective Not A Backend System,” API Evangelist (blog), April 17, 2017, https://oreil.ly/XCOTT.

18 Jason Costa, “A Tale of 2 API Platforms,” Medium, October 25, 2016, https://oreil.ly/ZzAlj.

19 “AARRR Pirate Metrics Framework,” ProductPlan, https://oreil.ly/GiDgb.