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

Continued from page 1. 

Anticipate what common mistakes developers might make, for instance using their test API key to fetch production data or vice versa—stating exactly this in the response instead of a neutral 404 error can save precious minutes for developers and create a better experience.

>> Stripe::Customer.create

Stripe::AuthenticationError: No API key provided. Set your API key using "Stripe.api_key = <API-KEY>". You can generate API keys from the Stripe web interface. See for details, or email if you have any questions.

>> Stripe.api_key = "sk_test_***"

>> Stripe::Charge.retrieve("ch_19wpz1Aq9p2uYn7E93WGqiCS")

Stripe::InvalidRequestError: (Status 404) No such charge: ch_17SOe5QQ2exd2S; a similar object exists in live mode, but a test mode key was used to make this request.

In addition, provide developers with complete request logs to make debugging much more convenient when any scenario they had not planned for arises.

Design useful error codes and messages

6. Support: bake it into your API from the beginning.

It's obvious how critical reliability is: developers build their own products and businesses on your API, and they're trusting you to provide a rock-solid foundation. But no API is perfect, and when things do go wrong, it's just as important to provide a great experience as when things go right.

For one, think about developer support as part of the core product experience, not something to be bolted on later. What is the preferred way that developers will want to get in touch with you when they have problems? Stripe has a dedicated developer support team—who are themselves engineers—available on IRC, StackOverflow or email to answer questions and provide technical guidance for developers.

Secondly, transparency is paramount. Provide real-time status updates on critical issues with your API's availability and service quality on both your site and Twitter. Being open, clear and transparent is key to inspiring confidence. Behind the scenes, this requires robust monitoring and observability capabilities in your systems and clear escalation paths for flagging issues.

7. Updates to the API: whenever possible, avoid breaking changes.

Shipping frequent improvements to your API is great; breaking something a developer has built is not. Finding an elegant balance is critical—and one way to do it is to avoid breaking changes. This has been Stripe's approach: we provide near-total backwards compatibility to ensure that code written today will still work years from now. We do this by locking the API version that a developer is using once they get started. Unless they actively choose to upgrade (because they want to take advantage of new functionality), we won't require them to do so. Behind the scenes, new features are behind discrete gates, which make it easy for Stripe to manage access to new features, separating layers of logic for requests and responses, and essentially hiding the backwards compatibility from the main codebase. Amber Feng detailed this architecture in her talk "Move Fast, Don't Break Your API."

Update the API

8. Think bigger: what else can you do to help developers succeed?

Communicate frequently with your developers, keep tabs on which frameworks and tools they're using, and build products on top of your API using them to constantly re-evaluate the developer experience. Having a dedicated developer relations team of engineers and storytellers can help inspire developers to build on top of your platform, craft great resources for them to get started, and champion their interests by translating their feedback into actionable product insights.

More broadly, think about what tooling might help your developers be more effective and successful in the long run—even if, on their face, those tools don't seem core to your business. If they don't exist, go build them. If they do exist, consider investing in their development, or contributing financially if they exist as an open-source project. As you build trust and mutual dependence between your developers and your company, it'll behoove you think holistically.

That's why we're excited about the potential for RunKit, a simple environment for developers to quickly prototype and explore new ideas with truly zero configuration where you can instantly use all the building blocks from the Node.js community.

Help developers succeed


APIs are the building blocks that companies of the future will be built on. They are catalysts for ideas, igniting creativity and enabling experiences that were previously difficult—if not impossible—to achieve. But providing an API means establishing a different kind of contract with your developer-customers. The more consistent, transparent, and easy-to-use your API is, the more successful you'll be in supporting a healthy ecosystem of developers building increasingly sophisticated products of their own.

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


Comments (0)