Building for Builders: Stripe's 8 Tips for Designing APIs and Supporting Developers

Over the last 15 years, it's become not marginally but radically easier for software developers to start a company. Between 2000 and 2015, the amount of money required to start a tech company dropped by three orders of magnitude, from a few million dollars to a few thousand. Why is that? Certainly the emergence of open source helped, followed by the era of cloud computing; a basic instance on Amazon Web Services or Google Cloud Platform costs as little as $15/month. But in the past five years, this shift was driven by a more specific cause: the rise of the API economy.

APIs are fundamentally changing the way we build software. As late as 2011, most tech companies didn't have APIs, and those that did had to be active advocates for them. Today, developer platforms and APIs have become ubiquitous. Companies like Twilio, Algolia, Sendgrid and Pubnub have built their entire business around providing an API. Today, two developers in a garage have the same capabilities at their fingertips that a decade ago was only available to the world's largest multinational corporations.

Still, there exists a huge range in the quality of developer offerings. As the API economy continues to mature, companies must compete not simply by having an API, but by providing a truly great developer experience.

For service and infrastructure providers thinking about offering an API as your core business, here are eight things we've learned while building the Stripe's API. And for all the other developers out there, consider these 8 items when evaluating the quality of the APIs you might use.

1. Incentives: align your business with your developers' needs.

Many successful tech companies build their product first and then add an API as an afterthought. At best, their API becomes orthogonal to their business; at worst, it winds up diametrically opposed and shuttered within a few years. We've seen for instance Netflix, Spotify, and Venmo make radical decisions around their API.

So before you start down the path of building an API, consider some fundamental questions: if developers start using your API en masse, will that be good for your core business? And conversely, how will your success make them more likely to succeed? Aligning your business incentives with the interests of the developers will ensure you're likely to prioritize the right things over the long term.

2. Engagement: provide a speedy on-ramp.

As a company providing an API, it's important to catch developers' attention—to give them a clear idea of how something works and the benefits of using it—within a few seconds. Don't make them spend 10 minutes creating an account and logging in; let them play with your API right away. Give them a snippet of code to copy and run so they can immediately see an actual result. A great first impression and a delightful, surprising moment is key to adoption.

Provide a speedy on ramp

3. Programming languages: support them, as many as you can.

Developers use a more diverse set of programming languages than ever before. Provide an SDK for every major development environment to make it easy for developers to get started. By installing the SDK that corresponds to their environment, they won't have to worry about specific parts of your API, and you can provide abstractions for some advanced behaviors. For instance, the Stripe Ruby Library contains some retry logic in the event of an error, adding idempotency and exponential backoff on retries when errors occur, improving robustness and predictability for developers and end users.

The obvious caveat is that SDKs don't replace great API design. Developers should always be able to get started with an API very easily, or use third-party libraries for the long tail of useful languages like Rust or Haskell.

4. Documentation: make it dynamic and personalized.

Don't think of your API documentation as a static user manual. You can reduce friction for new users by doing customization work on behalf of your users. Provide useful snippets of code they'll need to get started directly in your documentation. If they're logged in, populate those code snippets with their API keys so they can directly copy and paste the code from the reference into production code. Consider populating sample objects coming from the developer's account so they can intuitively grasp the meaning of each functionality in the context of their own data.

Dynamic documentation

You should obsess about every detail of your documentation and optimize for how developers will actually integrate your API. In the Apple Pay on the Web example shown below, we started by defining the JavaScript code that would feel right from a developer's perspective (i.e., easy to integrate). Next, we made that code a reality, and then, still prior to launch, we made it possible to see that code in action right inside the documentation. This provided a great experience for developers from the first moment that Apple Pay on the Web was publicly available.

Dynamic documentation

The State of API Documentation 2017 report makes a strong and detailed case for the importance of providing top-notch reference materials for developers.

5. Error codes and messages: design them to be genuinely useful.

It may sound obvious, but developers who are new to your API don't know what they don't know. Use smart error messages with explanations that make clear what happened, and what the likely fix might be. Even better, like your documentation, customize error messages for each user, referencing their own data when it makes sense.

Be sure to read the next API Design article: Fog Creek Software Announces Launch of Glitch for Platforms