The importance of “Time to First Hello, World!” an efficient API program

A long time ago in my second API program, I had the pleasure of working together with a dedicated API developer evangelist. His task was to evangelize the APIs to developers and to make sure the platform we were building was fit for consumption by developers.
Working with a dedicated API evangelist resulted in not-so-standard KPIs, rather than the usual 99 points how many 9s KPIs for system and API availability. A new KPI included the time it took to sign up, getting access to an API program and reading the required instructions to understand on how the API program would work and get a first response from the API. In the API world, we call this the “Time to Hello, World!”. During that period, the API team set the KPI for a developer getting access to our APIs and actual result of using the API to be less than 30 minutes. (The record for somebody to integrate their online service with our SMS API starting from when he landed on our developer portal was eight minutes.)

Focusing on the API program

This is not the first blog on the subject of “Time to First Hello, World!”, nor will it be the last. I do want to reiterate the story. Having spent some time now on the vendor site with Axway, I have seen how easy it is to forget the consuming part in the API Management lifecycle, as well as how API teams not always focus on the effectiveness of the API program for their (internal/external) customers. Instead, I noticed that people are getting way too comfortable in focusing on security and the prevention of easy API consumption. Reason enough for a small blog to help API teams focus on what in my opinion is one of the most important items when creating a namely, easy API consumption.

On the part of security, my take from obsessing over easy API consumption is that it does require very advanced API security, not the one that makes it impossible to invoke the API, but the one that uses a well-thought-out system to protect the API, but still provides easy access for those allowed to use the API program. Bad security stops API consumption and will make your API program ineffective.

Lessons learned with the API program

The biggest lesson if you want to create an API Management platform that drives innovation and digital transformation, you need to make sure your APIs are easily consumable. Since that is easier said than done, you need to measure this and make it a core KPI for the entire team who is creating your API platform. Don’t make assumptions that developers are already aware of how your program functions, always assume you have a fresh developer with no account, no API keys, no certs and step in those shoes. It is a KPI for the entire team, the API developer (or API designer if you have that luxury) will need to design the API so that it can be understood in little time. The API owner will need to provide easy to understand example (code) and simple and short documentation. The person responsible for the API portal will need to make sure people can self-register and can get access to APIs even if they need to provide some sort of dummy data or an API Sandbox environment.

There are different thoughts on the optimum time for a “Time to First Hello, World!” KPI. The 30-minute target is not easy, and therefore a good challenge. It also depends on the value an API brings if there is larger value for the developer he might try a bit longer before he goes off to another adventure.

Some of the Do’s and Don’ts in achieving a low “Time to First Hello, World!” are related to provisioning. Putting manual steps in the provisioning process incurs a big delay, so it’s best to avoid them. Instead to reconfirm a developer’s identity during registration a confirmation mail to activate the account is a good idea. In some cases, API programs do not want to accept generic mail accounts, and only want to serve people with dedicated domains (blocking Hotmail/Gmail/Yahoo). It reduced spam and unwanted, but it also reduced wanted developers, the usefulness can be debated. If you are using single sign-on (SSO) for internal developers, you are already one step ahead. For public authentication, the ultimate way is to use the GitHub login. Having different SSO ways on a single portal can be done, and from a maintenance point of view, having one portal change its behavior depending on who is logging in, is often the most cost-effective way. However, if you want to adjust the onboarding and customer experience to different communities, nothing is stopping you to use different portals for each of the communities. The most obvious example would be to have a different portal for internal developers and to have a public portal for the partners/external developers, that is for the companies who want to treat external developers different from internal developers.
The provisioning of API keys or access to the APIs is also a key point in the customer journey. Again, it is essential for developers to generate and delete their own keys, if there is a manual provisioning or approval step, it is going to impact the onboarding time. So it’s better to approve a key which gives limited access, than having somebody wait on a manual approval. Last using Swagger style API documentation has lots of benefits, one is that sample code is generated by the system. Sample code or sample applications shorten the time it takes developers to write their code, which is the last bit of the developer journey. Getting the code to work easily is very important, besides the sample code there are other options, a popular option is to make postman collections available. They are very effective and easy to change once downloaded. To see a complete flow of API calls in action, putting up a sample app (and the source code) is always a good option. The sample options are not mutually exclusive, but by combining them you can cater for different personas visiting your developer portal.

Last but not least

Last but not least, as good as an API program can be, there will always be standard problems people will run into. Maybe because they are not used to the time and date format you are using or don’t understand your authentication mechanism. Sometimes it’s OK to have these standard problems, sometimes it means you will need to change the API, but if there are questions which are coming back on a regular basis, make sure you either capture them at an obvious place in your API documentation (have a chapter for FAQs) or have an easily accessible forum which is dedicated to your API.