Your API developer portal is where current and future stakeholders will go to learn everything possible about your API(s) and even your company, both from a technical standpoint and also just as importantly, from a business standpoint. There are many facets that go into the leading API portals and ProgrammableWeb has created a series of articles that help you understand what best practices are being used by the top providers.
The initial article in this series provided a comprehensive checklist of the criteria needed to build a world class API developer portal. Subsequent Editor’s Choice articles including this one will provide a more in-depth look at how individual providers have executed on the various criteria.
This article looks at Stream, a provider of an API that helps developers build scalable feeds, activity streams and chat messaging. On Stream’s portal, it has nailed the critical part of the developer experience (DX) that we at ProgrammableWeb call Time to Hello API. This is when a potential user of your API has learned just enough about it to give it a try. This is part of an API developer’s overall goal to give developers a feeling of success quickly and with as little friction as possible.
The landing page for the Stream Feed API presents visitors with clear calls to action (CTAs) to try the API. Developers are promised that Time To Hello API will only take five minutes, a nice incentive for anyone still getting familiar with the service.
Figure 1: The Stream Feed API landing page presents a clear CTA to try the API, promising that it will only take five minutes.
After clicking on the link for the Feed API, the developer is shown a Getting Started guide; in this case, it is an interactive tutorial that promises to help developers build a scalable newsfeed that shows the activities from the people they follow. One thing we like to see is tutorials being offered in a number of languages. Here, the Getting Started guide has options for six different languages.
Figure 2: The interactive tutorial is offered in six languages. The UI shows both the code and a mockup of user newsfeeds.
Before they can access the tutorial, developers are asked to sign up for an API key. In keeping with the best practices for onboarding new users, Stream asks developers for a minimum of information. The registration requires developers to either enter a username, email, and password or they can sign in using their GitHub account.
Figure 3: Users can get an API key by only having to submit a username, email and password, or by signing in with their GitHub account.
Once registered, the developer is shown the first code snippet. It’s worth pointing out that the user’s API key has been automatically added to the code, saving the step of having to copy and paste it. As personalization features, this dynamic insertion of the developer’s API key into the online reference material is something we first observed in PlanetOS’ API developer portal and we’re seeing more of it across all the API developer portals that we look at.
Figure 4: After registration, the user’s API key and access token are automatically filled in, a nice time-saving feature.
From here the developer is taken through several steps of the guide including how to post a message, sharing a post, following another user, setting up aggregated feeds and subscribing to feed updates. Stream has done a good job with the guide’s user interface (UI), offering a window to view and edit the code, and a mock of the user’s own newsfeed as well as a newsfeed of one of his followers. This interactive UI allows users to edit and run the code, and see the results in real-time. The simple, interactive nature of the guide lets developers play with the API, build momentum, and finish it in five to ten minutes.
Figure 5: The UI gives users early wins by offering tips for how to edit the code and showing the results in a mocked-up newsfeed.
In our aforementioned Developer Portal criteria article, we discuss what goals an API provider should aim for with their onboarding procedure and Getting Started guides. These include:
- Self-service registration that requires a minimal amount of steps
- The Getting Started guide should give the developer an understanding of how best to use your API without going into extreme detail
- The guide links out to other pages that provide more depth on particular topics
- It covers common use cases
- The guide helps the user experience short-term wins and encourages them to explore the API further
As we have shown, Stream does a good job of minimizing developers’ Time to Hello API. The registration form only asks for three pieces of information and alternatively offers the option to sign in using a GitHub account.
The guide covers some of the most common use cases a developer would be interested in. The guide takes users through the basic steps needed to demonstrate the use cases but skips many of the details in exchange for quick results that the user can see. This helps developers experience early success and builds excitement to continue playing with the API.
Finally, when finished, the guide provides a number of links to in-depth tutorials on the topics covered. It also shows a link to the full API documentation for developers ready to dive in.
Figure 6: Once the user is finished with the guide, they are presented with links to in-depth tutorials and API documentation.
Overall, Stream offers one of the best onboarding experiences around. It has created a developer experience that helps users onboard with minimal friction and lets them see how the API works under several use cases, all within five minutes. If there’s one major beef we had with Stream’s DX, it’s that we could not find a primer on streaming APIs that helps developers and other visitors to understand the key differences and use cases for evented, streaming APIs (APIs whose activity is typically, but not always, triggered by a server-side event) versus the more commonly found RESTful APIs. That said, other providers would do well to study what Stream has done to incorporate many best practices into a seamless experience. For these reasons, ProgrammableWeb would like to give an Editor’s Choice award for excellence in Developer Experience (DX) to Stream.