Best Practices: How to Engage Developers with a World-Class API Portal

By most accounts, the API economy is now, in 2019, about 15 years old. In terms of the famed hype cycle from research firm Gartner, the API economy is so old that it's not only past the peak of inflated expectations (an early but disappointing phase for many nascent technologies), it has also roared its way like a lion out of the trough of disillusionment (the hype cycle phase that chronologically occurs after the inflated expectations stage).

Today, the API economy is a thriving industry in which many of the solutions and best practices have reached a well-seasoned maturity (although there's still plenty room for improvement). As such, we at ProgrammableWeb thought it was finally a great time to launch an Editors' Choice program in which we draw attention to the best practitioners when it comes to developer engagement. Particularly when it comes to how API providers engage their developer communities through developer portals, other online presences, and physical world engagement.

But before we could launch such a program, we thought it would be best to transparently establish and publish a baseline methodology so that the entire industry had some idea of what we at ProgrammableWeb believed to be the state of the art when it comes to developer engagement. At the same time, we also realized that this same standard could serve as an aspiration for many API providers looking to improve upon their engagement tradecraft. So, what follows isn't just the basis of how we judge the many developer portals that we encounter in the course of reporting the news of the API economy or running ProgrammableWeb's API directory. It's also a guide to any API provider looking to win the hearts and minds of developers, regardless of whether they are internal or external to their organizations.

As we see more advancements and innovations in the area of developer engagement, we will very likely take them into consideration as part of this standard. In other words, we'll be updating this document on a regular basis. Shortly after we publish the first version of this document, we also plan to start publishing our editors' choices for excellence in developer engagement. In the meantime, if you have any questions or suggestions regarding our Editors' Choice program, please do not hesitate to contact us at


In the past, an API Developer Portal was simply the place where providers housed their API Documentation. And for those early days of the API economy, that was certainly sufficient. But as more organizations start to understand the competitive role that APIs will play in establishing their businesses as game changing platforms, the more their API developer portals bear significant responsibility for brand positioning and marketing, partner and developer recruitment and communications, and ultimately business success.

As evidenced by some of the world's leading API providers such a Twilio, GitHub, and Stripe — companies that have generated significant success through their API strategies — the API developer portal must be viewed as the shiny new shingle that organizations hang on the Internet to say that they're open for digital business. Simply put, a developer portal can no longer be just about documentation (as it once was).

Today, 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. Whether it's intended for internal consumption behind your firewall, external consumption by third party developers and partners, or both, your APIs represent you and your business. The finish and elegance of the User Experience and the degree to which it breeds confidence across the various participants in your digital ecosystem will be a deciding factor in who wins and who loses in each industry. Your APIs are actually products and you should treat them as such.

What goes into an industry-leading API portal? To create the best portal for you and your developers, ProgrammableWeb walks you through what some of the top providers are doing, what their best practices are, and the elements and neat conveniences that make for a great API portal. It should be noted that while many API providers are putting a variety of industry-leading best practices to work in their API portals, no single API provider puts them all to work. In other words, there's room for improvement in every API portal we've seen.

Editor's note: As previously noted, this article draws on many examples of great developer portal best practices from all over the API economy. Wherever possible, we link to the actual examples so you can see for yourself. However, please be aware that by the time you read this, some of those examples may have changed or may no longer work as described. We'll do our best to keep this document as up-to-date as possible.

A portal has many jobs to fill, including (just to name just a few):

  • Articulation of the organization's unique value proposition as an API-enabled Business-as-a- Platform ( BaaP) to its stakeholders
  • Clearly stating each API's business case and suggesting the types of problems it can solve
  • Having top-notch documentation that's as easily consumed by beginners as it is by experts
  • Helping developers to begin sampling and working with the API quickly (what we at ProgrammableWeb like to call "Time to Hello API!")
  • Establishing trust in the API provider as a business, confidence in the security and reliability of the APIs, and providing world-class support

We'll show you the API portals that do this well and we'll even call out some that don't quite hit the mark. We even have some ideas for world-class developer portal features that have yet to be observed in the wild. Armed with this information, nothing stands between you and building a truly standout portal that engenders interest in your API-led BaaP while launching your API-consuming developers confidently into their projects.

Continued on page 2

Be sure to read the next Developer Relations article: 5 Tips to Build Developer-Friendly API Products