Even the best APIs in the world have leaky funnels. Potential users get as far as signing up, maybe even completing that action, only to abandon the process. In some cases, the reasons for this are unavoidable. The product might be too expensive, for example.

In other cases, something happens between signing up and the process of actively using an API. Examining how far people get in the sign-up process might help you to identify the reason for this drop-off but, then again, it might not.

In this article, we’ll be looking at some of the reasons a potential user might give up on an API before they’ve started using it. We’ll also be looking at tried and tested ways, along with some emerging solutions, on how to reduce API abandonment.

Show, Don’t Tell, (With Code Samples)

Geoffrey Moore’s Crossing The Chasm is a book on tech marketing published back in 1991. You’ve likely seen the book’s signature chart, a bell curve that visually outlines the pattern of innovators, early adopters, the majority, and laggards in tech adoption.

Trying to apply this to APIs, writer Jarkko Moilanen suggests that the API chasm — dividing early adopters from the early majority — is 3 minutes wide.

To maximize engagement early on, he theorizes that potential developers should be able to test APIs using code examples within just 180 seconds of engaging with the product. While that may be overstating the importance of copy-paste code samples, his thesis is an interesting one.

The idea that code samples are as important as, although maybe not more important than, documentation is one that it’s difficult to disagree with. In an analogy, it’s unlikely that you’d buy a digital camera after looking at its instruction manual without seeing some pictures taken using it or holding the camera in your own hands.

On the idea of “holding the camera”, providing a sandbox is a great idea if you can provide one. If not, consider a free trial or a freemium model.

Creators of paid APIs might balk at the idea of giving away calls for free, but maybe they shouldn’t — giving developers free rein to explore an API before committing to a purchase is part of a good onboarding process.

If a small number of monthly calls is enough to fulfill their requirements, they were probably never going to sign up for a paid account anyway. At least, in this model, they remain active and might upgrade if their needs for your service scale-up.

Support vs. Peer Support

Chris Chandler, founder of sudoHERO, suggests that “unlike other groups of customers…developers actually prefer to find answers by reading through information which might be of use to solve their problem before engaging a support rep.” A small-scale study from 2017 suggests the average developer makes 16 searches a day to do their job, with one major search category being “Understanding an API.”

That’s not (just) because developers don’t like to admit defeat when they’re facing a problem. Chandler continues that “to accurately diagnose a problem, countless variables need to be communicated in order to replicate the issue and provide a reasonable reply.”

When submitting a support request, some of that important context is often missing. The result? “After waiting hours, or even days, for a response, initial support tickets may be responded to with a request for clarification on some part of the question. Once provided, the message goes back into the queue and the developer waits…Again.”

In other words, offering 24/7 support might not be quite the selling point you think it is.

Peer support, which feels more like brainstorming with fellow developers than submitting a support ticket, can be a compelling addition to the onboarding process because it gives potential users a sense of what those already using the product are doing.

This is something that Miro does well, with an appealing UI somewhere between Hacker News and a ’90s forum. Note that Miro’s Developer Relations Lead regularly jumps in to help people out; this helps the support site feel more like an active community, full of searchable Q&As rather than people shouting into the void.

This is a very different ballgame than searching for an issue with your MacBook or iPhone on Apple’s Support Community and finding hundreds of other people with the same problem… but no one with a solution.

The Documentation Paradox

Brian Helmig, Zapier’s CTO, said the following in conversation with Codementor: “information should dispense automatically by design, when it’s needed.”

We’ve written time and time again about the value of great documentation, but there’s a type of conflict implicit in doing this successfully: the best API documentation should be digestible enough that it doesn’t overwhelm, but should also include everything (or close to it) a developer could ever need to know. Those ideas stand at odds with each other.

Using automation, Chandler is trying to solve this problem with sudoHERO’s Contextual Support tool. He suggests that “when working on troubleshooting an issue, the developer typically goes back to the documentation first to review the syntax and confirm their understanding of how a command or function should be used. If an answer isn’t found there, they’ll then look elsewhere for additional information.”

Clearly, that’s not ideal for API developers who would rather keep consumers in “their world”.

To combat this drift, the company offers a tool companies can use to embed knowledge base articles and relevant insights from other developers directly into their documentation:

We’ve already seen companies like Yext looking to shake up search for consumers using AI, but the idea of “going beyond search” has some really intriguing possibilities in the context of the API space.

The current version of sudoHERO’s Contextual Support surfaces relevant information from Discourse developer forums and select tags from Stack Overflow, so it’s best suited to products that rely heavily on developer communities to support their users. However, Chandler says that an additional solution is in the works for companies that depend on ticketing systems (instead of developer communities) as well.

Based on feedback over time, the product gets better at delivering the best available answer to developers. In turn, tools like these can identify which parts of their documentation generate the most queries and can use that information to clarify it.

Measure & Iterate

Cultivating an engaging developer experience is not a “one and done” process. When you first create your developer portal and documentation, there’s a significant amount of guesswork involved. But, as time goes by, you may want to refine this process.

Finding a way to track the behavior of users, and potential users, in your API portal is a great way to identify bottlenecks and areas of interest. When you know what those are, you can address and accentuate them respectively.

Pronovix’s Zero Gravity developer portals are an example of such a documentation experience, prioritizing iteration and an engaging editorial experience for authors/editors.

There’s (much) more to creating compelling documentation than just using an OpenAPI spec and Swagger tools, some of which can be used to generate multiple documentation versions from OpenAPI specs, but it remains a good starting point.

Final Thoughts

In our article on the importance of Time To First Call (TTFC) as an API metric, we talked about aiming to remove roadblocks in the process of signing up and getting started with a product. Above, we’ve outlined a few key ways to do that:

• Code samples to give people an idea of how to use the API
• Extensive documentation once they’re ready to jump in themselves
• Going beyond traditional support by building communities and better context
• Iterating on the processes above based on feedback and analysis of user behavior

The title of this post states that API onboarding is broken. That’s not always entirely true, but API onboarding often does lag behind some of the well-established funnels that exist in the SaaS space. And, with APIs now being respected more as freestanding products, there’s no excuse for that.

Fortunately, it appears that tools and systems are on the way (or here already) to help API developers take their onboarding to the next level.