Eight tips for API design: Romain Huet at DevXcon

Romain: Thank you all for having me today. Super excited to be at devco and it's awesome to see a lot of familiar faces, but also like a growing community, caring so much about dx. So I work at Stripe based here in San Francisco. I focus a lot on developer relations and developer experience for our platform and APIs. And today I'd like to share with you some concrete tips from the lessons we've learned building the Stripe, API, and hopefully you can apply as well to your own companies and developer platforms. Before we dive in, I'd like to spend a moment just to talk about the API economy and the growing impact it's having on our society and why DX matters so much. In that context, infrastructure might be underrated, but it's actually essential for any economic growth.

As an analogy, you can think about building APIs and developer platforms the same way as building roads, for instance. By providing an API will not stipulating an end state or particular destination by providing an API we creating and expanding the network of possibilities. So when you make roads, obviously you open up a whole new industry for car makers, but you also create an entire range of opportunities for businesses and individuals the same way. And over the last 15 years, what's interesting is that it's become radically easier to start new companies. When you think about that graph between 2000 2015, the amount of money required to start a tech company as dropped by three orders of magnitudes from a few million dollars to just a few thousand now. And so you might honour why is that? Well, surely there was first the emergence of the open source and then the cloud computing.

That really helped because an instance on the cloud is now just maybe like 15 bucks a month, but in the past five years, it's mostly been driven by the rise of the API economy. APIs are really fundamentally changing the way that we build software. And as of late 2011, most companies did not really have APIs out there. Or if they had one, they really had to advocate for it. Now, developer platforms and APIs have become ubiquitous. Companies like Nexmo, Algolia, SRID have all built entire businesses now around their platform and their APIs. And when you build companies, what really matters is the focus you have and your agility, the ability to concentrate all your efforts on building a unique product and have key differentiators on the market. Still there exists a huge range of quality in terms 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 experience for it. So with that, I'd like to share with you eight concrete tips from what we've learned at Stripe on that front. The first one is about incentives Over time. We've seen a lot of tech companies build their product first and then later on add an API to it. At best, the API becomes kind of orthogonal to the business, but at worst it ends up in some very complex situations. We've seen companies like Spotify, Netflix, Venmo, or sometimes Twitter also making some difficult decisions around the API over time. And so before you go down that path of building APIs, really consider some very key questions. The first one, if developers start building on top of your APIs today, will that be good for your business in the long term?

And on the flip side, how will your success make sure that developers are also going to be more likely to succeed? So really align your business incentives with the interest of the developers in mind. When you think about building an API at Stripe for instance, we're building a platform to help more businesses get started and help them grow their reach and the entire company revolves around the API. So when you think about when the first few lines of Code for Stripe were written in 2009, the goal was actually to fix a very specific deficiency in the internet infrastructure. A clear need for a lot of developers out there. We all know the foundational protocol of the web. HTTP defines a lot of things like error codes, codes, for instance, that we've all become familiar with. Like 4 0 4 page not found, or 4 0 3.

Do some of you know what 4 0 2 means in the room?

So 4 0 2 is actually funny. It means payment required, but all the spec says ever is reserved for future use. It's never been flashed out. So the architects of the internet knew and the web, they knew it would be super critical to figure out what payments should look like and how it must work, but never really had the chance to define it properly. So that's why we build Stripe. And so when you're building a company today, payment is too important to actually handle it yourself, which is just reuse infrastructure that already exists out there. So before you build your API, whether it's your core business or something that you compliment with this API try to make those incentives super aligned and make them very sharp so you know exactly that it's going to be a win-win for both you and your developers. Next, let's talk about engagement.

The key here is that you want to have developers super excited about your product in just a few seconds. The first few seconds a developer will spend on your site are actually critical. It's important to catch their attention right away and give them a clear idea of how something works before they can actually use it in their own product. So since the early days of Stripe, we've always made code front and centre on the site. It's still the case to this day. We have here modern JavaScript snippets on the homepage and you can actually have a sense of how the product works and how you can use it. And once you've got developers' attention, don't make them spend 10 minutes screening an account or even logging in. Just let them play with your API right away.

Give them a snippet of code that they can use and give them a great first impression. So here for instance, on this screen, without logging in, I can just start tokenizing my very first credit card and understand, get a good feel of how the API works without the need to sign up.

Developers also use a more diverse set of programming languages than ever before. It's important to make sure that you can support whatever they use and the favourite technologies they're using every single day. So at Stripe we think payments should be rooted in code not in finance. And so that's why we approach the problem in the way that we think the architects of the internet might have. We offer libraries and SDKs for a wide range of platforms so developers don't have to worry about specific parts of the API from Python to node to go, we've got you covered. And we think that SDKs are really critical to provide a great DX beyond the classic rust DPI abstractions and SDK can help you with automatic object expansions for instance. So household network retries to make sure you don't have to implement all that logic yourself. And of course the other benefits of controlling the SDKs is that you know exactly what the snippets of code should look like in every language.

So that means you can bring them right in place in your documentation and people can just copy and paste immediately. And of course, libraries and SDKs do not replace a great API designs. Developers should be able to use any language they like maybe Rust or Haskell for which we don't have first class support. And at Stripe we also conduct API reviews on a weekly basis at the office and we bring a diverse mix of engineers from different teams, different background, and we review and discuss written proposals for any API changes from a simple new attribute in the JSON payload all the way to a new set of API endpoints. And we think that this time investment is really worthwhile in the wrong run to guarantee an elegant and cohesive API design.

We also try to share best practises to help developers be successful. So in this particular blog post for instance, we explain how we introduced item potency and exponential backup and retries when errors occur in production. So a payment would not happen mistakenly twice, for instance. That would be a bad experience for our customer and that improves the robust robustness and the predictability of the API and our libraries and SDKs take care of that automatically. We also recently published an article about rate limiting and how to prevent having bad actors damaging hitting your API reliability because we think that an API that's solid and reliable is also part of a great dx. Next, let's talk about documentation. We think the API documentation should not be a static user manual. We think developers should be able to integrate with your API in a few minutes no matter what your API does, it shouldn't take any longer to get something up and running.

Having great documentation is critical to win the hearts of mine on developers. If it's not easy to access or if it's not delightful to use, developers might just move on and try another API doing the same thing. And I'd like to walk you through some of the ideas we've implemented at Stripe on that front. First, we start by completely re-engineering the way we do docs by making them a single page app so they're much faster to load. The information architecture has been rethought at the same time and we added a lot of small touches and details to ease the DX along the way. And even the search with Algolia recently to make searching a lot faster. So in each snippet of code for instance, you will see that even when you are locked out, there's an API key waiting for you just here. So that means that if I copy this snippet, I will be able to just use it immediately without even a need to sign up.

We say, Hey, there's a demo key for you, feel free to use it, and everything will work just seamlessly for you. And then when you log in, we actually put your own keys right in place in every snippet, throw the dock. So that means you can just copy and paste. You don't have to go multiple back and forth between where is my API key, where is the admin to find them? Everything will work seamlessly for you. And each time you switch language, we also save those preferences in the browser. You can use the local storage for instance, to store that you should obsess about every detail of your documentation and optimise for how developers will actually integrate. That's an example of our launch for Apple Pay on the web.

So here if you're running Safari on a Mac, you can do a test purchase using Apple Pay on the web without leaving the Stripe site.

And we think this is a really good way to get developers engaged super quickly. And the process behind those demos is also interesting because here for instance, we started by defining the JavaScript code that we think would feel right from the developer's perspective. And then we made that code a reality by implementing it into Stripe js. And then finally, still prior to launch, we made it possible to see that code in action right inside the doc. So we tried to follow this approach for every new product launch where we optimise for the code that developers will have to write for grade DX and then we go back and make it happen.

Besides guides and tutorials, the API reference is also a key part of a Grade dx. If you're sign in, once again, we're going to populate your API keys in every snippet of code that you can use. So every copy and paste will work seamlessly, but once you start making some API calls the stripe API, we actually feed the data back inside the doc. So here you can see for instance, these are the values of my own accounts. So as I'm implementing the Stripe API for my own app, I can actually see a real values immediately. So it's a lot better and faster for me to understand what each of them are useful for.

And if you're curious, I can actually share with you what's happening behind the scenes to build this API reference the way we do it because every request and response have parameters that might depend on the API versions and so on. We actually have one main code base, like multiple services of course, but one main code base. And that really helps to have the API code and the API documentation in the same place. It's basically impossible for us to be out of sync between what the API does in production and the documentation simply because all of those leave at the same place in the code base. And that's what generates the API reference that you can see on the right side.

Next up, let's talk about error codes and messages. Docs are important, but they're not the whole story. Try to anticipate what the common mistakes developers might make along the way. So here, for instance, if I don't pass my API key when trying to use the Ruby SDK, well we give a direct link to go get the IPI key seamlessly or even better. In this second example, we noticed that you're using a test API key, but it looks like the object you're trying to fetch is actually coming from the production mode. So be smart with these errors when developers use their test key to use production data and vice versa, standing exactly that instead of just doing a neutral 4 0 4 will save some precious minutes for developers and once again, create a better DX for you. In addition, you can provide developers with complete logs of what happens live for HTTP and post requests. For instance, when they're running your API in production, they might see errors that they had not anticipated when debugging locally, for instance.

And so having all of these requests logs seamlessly available for them with all the parameters and the responses will surely help making their integrations a lot better.

Once developers have successfully integrated your API and they're almost about to go live, how do you give them confidence and assist them when they need help? It's obvious how critical the reliability of NMPI can be, but developers build their own products and businesses own your API. So you should really be able to provide them even when the API does not go exactly as they expected. So think about developer support as part of your core product experience, not something to be bolted on later. So what is the preferred way developers want to have help? Well, it depends. At Stripe, we have for instance, a dedicated support engineering team and they're available on IRC on stack of the floor on email, and they can answer questions and provide technical guidance to all developers Integrating with Stripe, even if you run communities and you grow them. Private communication channels can also be very important.

Make sure the exchanges feel like you're in the partnership with the developers, make sure you're trying to make them successful and that's going to really pay off in the long run and try to respond within hours. Don't let stuck for multiple days as they're trying to build with your API Bear will actually give a talk this afternoon at 2:00 PM on providing great experiences through support. So feel free to check that out.

Transparency is also paramount, like provide a realtime status update on critical issues of your API and the availability of your services. Being clear, honest, transparent is always key to inspiring confidence. So behind the scenes, that obviously requires a lot of robust observability into your systems, but that's really essential to flag issues and inspire confidence with the developer communities out there are. Next, let's talk about backwards compatibility and updates to the APIs. While shipping frequent improvements to the API is really great, but breaking integrations that people have written is not. So finding an elegant balance between the two is really critical to have a great dx. So that has been Stripe approach over the years. We are trying to provide near total backwards compatibility for every API changes that we introduce.

And the way we do this is by locking the API version that developers are using once they get started.

So for instance here, imagine there is a change that we're introducing, maybe like a renaming of an endpoint or a parameter. What we'll do essentially is cut a new version of the API for stripe. And that means that when you have a new version available on the dock will display this banner on top and then you can see the changes that might impact your integration. And only if you are willing to upgrade yourself. And if you feel like your integration is ready, you can just in a one click of a button upgrade to the latest version. And so the only exception to backwards compatibility can be security, for instance, when let's say TLS versions are too old and at some point you can have to upgrade. But other than that, we really believe that payments is the lifeblood of a business. And so even if we go fast and we constantly improve the API, we should never break integrations.

And I think that's a good approach to have in mind because developers don't necessarily have the time to always fix and upgrade API versions.

Behind the scenes, the new features that we introduce on the API are behind what we call discrete gates. And that means that every new version of the API will introduce new gates on our systems. And so we separate the layers of logic for every request and response and we try to hide all these backwards compatibility from the main code base. And so typically that's how we introduce new Gates where we have a YAML file describing exactly new versions and which what each of them does. And then we can provide a full and complete change log for developers to upgrade themselves when they feel they're ready with their integrations.

Last but not least, let's talk about how to think bigger in terms of if you're an API company and if you're building this great developer experience and maybe taking some of these ideas, we think you're in a good shape. We think you're going to really help developers be efficient in their work. Communicate frequently with your developers, keep tabs on the frameworks and the tools they're using and try to constantly reevaluate the dev experience yourself, like build sample apps, build products on top of your own API to see how it feels and how it behaves. But more broadly, think about the tooling that might help your developers when they want to be more effective and successful. If they don't exist, go build them. If they exist, maybe you can contribute to open source projects and help out. Building trust and mutual dependencies between you and your developers will truly help in the long run.

And so at Stripe for instance, we think about building software in a way that should be a lot easier. What it is today, for instance, when you start a new project in Node, you have to find all the right NPM packages and instal them to try them and then try many of them because the first couple ones were not exactly what you expected. And so that's why we're excited about tools like Run Kitt. They have a lot of potential to provide a simple environment for developers to have a safe prototyping environment to get started and really get their ideas in a concrete firm a lot faster. So here for instance, we have three lines of code to interact with an API from Open Notify that has the International Space Station position live. And so in just three lines of code, I can prototype something quickly and see exactly where the ISS lives.

So Run Kit automatically notices when you have all those coordinates, displays, a map and so on, to have something a bit more friendly and faster to integrate. And so you can even use Run Kitt in your own documentation to make it come to life. And so you can have those own embeds, and that's the low dash project as an example. So on the low dash documentation, if you are curious about how the compact method is working, you can just try it live within the docs to see if that's what you're looking for. And I'm really glad that those tools are helping developers get tied faster. But similar to Glitch this morning where you can also get help and develop software a lot faster than before. So APIs are really the building blocks of the companies of the future. They're like a catalyst for ideas and creativity.

So I hope these ideas about developer expense will help you as you are building your API or also evaluating some APIs that you might use for your own businesses. And we really think that DX is a constellation of details that all matter in some way. So yeah, I hope these tips will help you improve your own dev experience. Yeah, and of course we're always looking to improve. So if you have any feedback on the Stripe API or run kit, feel free to talk to me. I'd love to hear your ideas. Thank you very much.