Picking Favorites: Why No APIs Make My List

When I speak with a team for the first time about helping bring their API program to market, one of their most common questions is, "What is your favorite API?" I stumble on this one every time. 

Like most developers, my favorite API is the one that helps me get my job done at that moment. In an ideal world, a well designed, well managed API that delivers real value would be championed by every developer who ever uses it, and there are plenty of examples. But my perfect API is the one that gets me over my current hurdle and on to the next with a minimal amount of time and effort. In other words, the perfect API is one I may have ever only used once without ever needing to revisit it, and I may have forgotten all about it. 

Experience Matters

The heart of this is not necessarily the design of the API itself, but the experience of the developers using it. There are plenty of popular APIs that could stand a redesign - they deliver too much data in their payload, they require too many calls for common tasks, their data model is too complex for the domain they're serving, etc. - but the unique value or proprietary access they require makes up for it. Anyone who had to integrate with a payment solutions provider like Authorize.net back in the early 2000s experienced this first hand - it was complex, bloated, and leaned too heavily on esoteric calls and terminology that required many developers to become more knowledgable with the credit card fulfillment process than necessary. 

Payment APIs like these were the only game in town until PayPal implemented a simpler API - albeit still complex and bloated - that made payment integration much simpler. The documentation was cleaner, there were fewer steps involved, and there were more ways to integrate so developers with varying levels of skill and expertise could all create a successful integration. Perhaps most importantly, PayPal hid much of the credit card processing complexity from developers, allowing them to implement the functionality they needed without requiring them to be experts. Paypal rapidly eclipsed the established players and many members of their founding team were elevated to the geek pantheon.

Then Stripe showed everyone how to do it right.

Stripe was famously founded by two developers, brothers Jon and Patrick Collison, who found payment processing a major hassle in their own work. They developed a payment processing solution that could be implemented by any developer in just seven lines of code, completely hiding any of the complexity in their hosted application. Accepting payments was already a solved issue - the Collison brothers just solved it better. Stripe was rewarded by the developer community through rapid adoption and growth. For many, it's the de facto way to handle payment complexity. 

Twilio has seen similar success by abstracting the complexity of telecommunications protocols as easy to use APIs, enabling developers to send and receive phone calls and texts to create interactions on those platforms using the same code that drives their other applications. This alone is cool, but their developer advocacy and evangelism strategy is what puts them at the top of many lists. For a while, you couldn't go to a developer conference without seeing their cadre of red track jackets eagerly mingling in the crowds. Every single one of them was an expert in their services, and developers quickly associated that red jacket with someone who could help them solve their implementation issues. I once asked a Twilio friend if he could score me a piece of that sweet gear. He said yes - after I joined them as an evangelist. 

Know Your Developers

Both Twilio and Stripe arise again and again as examples of great APIs, but I'd argue the APIs themselves really aren't that special - there are plenty of competitors in both industries these days. These programs stand out because of how well they understand their developer customers, and how committed they are to serving them. 

I like to cite GitHub as my favorite example of a developer-focused organization. If you have used their APIs, well... I feel your pain. Don't get me wrong - they offer a powerful set of services that have enabled a whole new form of automated software delivery, collectively known as "GitOps", which allows an unprecedented level of programmatic access not only to my own code repositories, but anyone else's who decides to grant access to my application. But the APIs tend to adhere a bit too closely to the underlying git functionality and internal data models, requiring a developer to spend time shoring up their git knowledge. Many of the data responses are filled with data that is unnecessary, poorly labeled, or complexly arranged, which can slow development time and lead to confusion. 

But GitHub excels in how they respond to developer needs. What started as a hosted repository management system - a fairly complex system to host and manage on your own - has transformed into the core of most engineering organizations' automated DevOps processes. In these organizations, committing code to a branch in GitHub triggers a cascade of scripts to build, package, test, deploy, and monitor increasingly complex services and applications. Code repositories primarily exist to allow multiple developers to work on the same chunk of code without steeping on each other's work. GitHub extends this functionality with "Pull Requests", allowing multiple developers - even those outside the organization - to work on the same code, but preventing all but a handful of selected developers to merge that work with the main code branch. Engineering organizations have complete control over who accesses their code without requiring them to adopt any specific development paradigms or processes. 

Listen to Your Developers

Stripe, Twilio, and GitHub share a laser like focus on understanding the needs of their developer customers and delivering an experience that reduces their effort, delivers complex functionality while abstracting unnecessary details, and supporting them with documentation, learning materials, and personal assistance to push them through their challenges quickly and cleanly. Their ability to do this so well is due in no small part to all three companies being founded mostly by developers themselves. They understand the customer intimately because they have been there themselves.

To build a successful digital platform and developer outreach and marketing strategy, you need to start by understanding the challenges your developer audiences face. It's tempting to look at other successful developer programs and copy their efforts for a short win, a "cargo cult" approach that can work when you're trying to get from zero to anything as quickly as possible. But you must also focus on building a program where you can get immediate and valuable feedback from your developer customers, not only through how they sing your praises or curse your name, but in the patterns of usage of your services, how they access your documentation, and how quickly they go from onboarding to production with your products. 

If you're targeting your internal developers, you should work closely with engineering leadership to make sure you're getting the feedback you need. If you're targeting external customers, make sure you have someone on your team who understands them intimately and is passionate about making their lives easier while also building in metrics that give you quantitative feedback to help make better decisions that may clash with what you're hearing on the front lines. This is the difference between the mentality hiring a "developer evangelist" who will market your services and sing your praises to the developer community, and a "developer advocate" who will listen to your developer customers and use that feedback to help product teams better meet their needs.

Improve your developer experience by optimizing toward providing effortless value and you are guaranteed to become someone's favorite API, even if only during the short time they spend implementing it. 

Need help? I’m your man.