Why your API onboarding sucks and what you can do to improve it

API onboarding is about how easily (or the opposite) new API consumers learn how your API works, what it can do and what problems it solves. Most of the API owners want to have hockey stick growth rate in new API consumers out of which some end up paying for you.

The idea of freemium is simple. Provide a peep show.

To our pleasure, most of the companies have understood the value of self-service. In other words, API consumers are allowed to register instantly and get API keys in seconds. In addition, most API owners understand the value of freemium / trials. The idea of freemium is simple. Provide a peep show. Give the developer enough space to try and explore your API to become hooked. This is part of the onboarding as well.

You are creating hockey stick growth in learning curve, not in API consumption

The next steps in providing easy onboarding are not widely understood. API documentation is discussed a lot and it is super important. Yet it’s just part of the fluent onboarding. Most companies think that providing detailed API documentation is enough and even worse, providing a documentation based on OpenAPI specifications. If you stop here and think that it’s enough, you are creating hockey stick growth in learning curve, not in API consumption. You are throwing newbies to icy water without life vest. Even though some Finns like to jump into hole in frozen lake, most developers probably don’t. New API consumers should be guided with gentle hand towards the documentation if and when that even becomes necessary.

Even though some Finns like to jump into hole in frozen lake, most developers probably don’t

Basic usage of the API should be learned without going through extensive documentation. New API consumer should get the feeling of success as fast as possibly with minimal effort. That is your API’s wow effect.

Provide code examples — first touch

You need to provide quick start to onboard your API. Documentation is not the place where new API consumer is thrown. Developers love code examples. They don’t want to read documentation. You need to provide copy-paste code examples to new API consumers. Try to inject code examples in Open API driven API documentation and you’ll find out that it’s pain in the ass. You need to have something else. Stripe documentation is a good example of mixed API documentation. It contains easy to approach documentation and code examples.

Practical guides and peer support

Second layer of the onboarding is guides and working examples. Guides show in more details how things work with your API. Another good way to offer onboarding support for new API consumers is to provide conversational API documentations with help of Chatbots. Chatbots are integrated to working environments of teams (such as Slack and Flowdock) and by so offer instant access to documentation. An example of such API chatbot is apibot.ai developed by APInf Oy.

APIbot is now in beta and we seek customers to gain more feedback. Contact us via apibot.ai and get one chatbot for free. Another overlooked form of onboarding support is peer support, which can be for example Stack Overflow community.


Third layer is detailed documentation

Detailed documentation is the third layer of excellent API onboarding. Consumers should be guided to clear and up-to-date documentation when they need to learn your API nuances and become expert in utilizing it’s finest features. Documentation should not be the starting point.

patterns fit to 70–80 percent of the developers. Patterns will help you cross the chasm and boost onboarding significantly

Measure and learn — identify patterns

You need to learn what new and old API consumers need. This might sound like you would need a crystal ball. Your crystal ball is measuring. You need to measure the behaviour of API consumers in API portal. Measuring refers to tracking what they do, how they navigate, where are the dead ends when developer leaves and such. Based on the tracking you can see patterns. Even though people learn and adopt new information in unique ways, there are patterns. People are pattern driven machines. Patterns give us feeling of safety. Those patterns fit to 70–80 percent of the developers. Patterns will help you cross the chasm and boost onboarding significantly. Your API portal should be developed based on these findings and patterns. This might be manual work in the beginning and start to utilize artificial intelligence later. Big change in thinking is that you should treat developers as customers, they have customer paths just like any other customers.

APInf standard

The above values and principles is what drives me in APInf. The above is what I try to communicate to our developers and clients around the world. That is what I want to see in APInf.io API management platform to maximise developer love towards your APIs. Maximize your API onboarding experience through apinf.io — we have a free tier.

Like what you read? Give Jarkko Moilanen a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.