The global economy is directly impacted by the apps and services provided by developers, says Stripe’s Romain Huet. He discusses the lessons they’ve learnt at Stripe about providing developer experiences that enable developers to play their part in that global economy, in his talk from DevXCon San Francisco 2018.
Thank you, everyone. Good morning. Super excited to be back at DevXCon, I was there last year already. So at Stripe, we’re building the commerce infrastructure of the internet. And we are making it a priority to offer great APIs, great developer tools and overall, like a great developer experience. So as part of my role at Stripe, leading the developer relations efforts, like I spend a lot of time talking to builders, developers trying to understand their need and really how can we help them to be more successful. So last year at DevXCon, I presented eight principles of what we consider really important when you want to build a great developer experience and based on the lessons we’ve learned at Stripe, building the API and scaling it over the years. So I’d like to start with a quick recap of those aspects that I shared with you last year. And then we’ll dive into more bigger, more interesting and bigger challenges that developers are facing today in the API economy.
So, quick recap on those eight principles. The first one was clearly about aligning the incentives with your developers, meaning that if your developers are assigned to use your API massively, is that gonna be good for your business? Very important question to start opening up an API. Second, really about providing an easy on-ramp. Like, it should be very easy for developers to start. In just a few seconds, they should be able to understand what your API is about and has to offer. Next, supporting developers with older developer environments they’re using today. With like a lot of SDKs, client libraries and making sure they have all the tools they need. Next, we talked about dynamic and personalized documentation. Don’t think about documentation as a static user manual, but try to make it really personalized, interactive for developers to really deeply understand the product. Think about error messages and error codes as part of your API design as well.
Of course, a solid API has to be reliable and always available. So be transparent with your users, have a status page, talk to them on Twitter, and other channels. And, of course, build the support in your API from the beginning, like, developers support is a key component of a great developer experience. If you can, offer backwards compatibility API, so this way, developers write code at any moment but they will have the guarantee that this code still works in the future. It’s a great way for developers to have confidence in building on top of your platform. And last but not least, kind of thinking about bigger ideas and tools to help empower developers when they build on top of your platform. So these were eight principles I shared with you last year and really developer experience there, you can see is about a constellation of details. All of those, as you can see, really matter in the overall developer journey when they use your platform.
So as a provider, we think that if you have those principles in mind, you’ll be in a great shape when you offer an API. And as a developer, you’ll have the ability to assess whether an API is a good foundation for you to build upon. So, now, we’ve been building these kinds of tools and we can start thinking about, like, the last principle a bit more deeply. Like, how can we move forward? Because at Stripe, we sit at the intersection of two spaces. One is economic infrastructure, and the second is being an API provider. So how can we really push the API economy forward and help developers be more successful? So we’ve been thinking about developer infrastructure in products for a while. And we rely on payments as our core mechanic. The same way as Google Cloud and AWS provide the technical backbone of the internet, we think of Stripe as providing the commerce backbone of the internet, if you will.
But there is this overarching connective tissue that threads through the old platform on top of the products that we provide. And all of these products are also APIs, by the way, and this overarching connective tissue is really the developer experience. It’s the tissue that threads through the whole platform. And so when we think about developers, we wanna increase their leverage and that’s why having a great developer experience matters so much. What’s interesting, though, is that in computing the best developer experience have always tended to be like very full-stack.
For instance, if you’re building a mobile app, you have Xcode, you can put breakpoints, you can, like, debug your app, analyzer system, API calls, and so on, same for Android Studio. Or even to this day now, when you have code in VSCode, for instance, you can instrument all the way end-to-end node in your browser with all the end-to-end debugging. So you have all these interfaces that give great power to developers. And they have a good sense of what’s happening and how they have, like, this grounded awareness to debug and implement their product.
Now, how do you build the full-stack experience when you’re providing an API platform instead? And we believe that builders should spend as little time as possible dealing with APIs because what they really should focus on is really what makes their product unique. Like, what is gonna take their products next level? And so with the emergence of the API economy, it looks like something has changed in what we expect to be a paramount developer experience. APIs are way too often black boxes, you end up with, you know, specifying some requests, you get some responses, but you don’t really have a great visibility. And in the worst cases, you don’t even know why an operation failed in the first place.
And the reason why people are okay with giving up this control is because APIs represents a contract that help them build their businesses. APIs have a great set of predefined terms, if you will, on top of which you can build your products. And APIs are very cost-efficient, it’s a great way to build products in businesses because you have this infrastructure out there that will keep improving over time. And so as you build on top of those APIs, you will future proof your apps. But the thing is, what does that mean for the developer experience that you provide, and the one you consume when you’re building those products? And today, like the state of the API development experience is largely focused on documentation and specification, things like GraphQL are definitely pushing, you know, the ecosystem forward. They’re exciting because they let you specify the kind of data you’re looking for. But even that is not quite enough because, at the end of the day, you have better ways to query your APIs, but it doesn’t really open the black box.
So two questions came up to us as an API provider, that we found critical for this conversation. The first one is, “How can we help developers build a tactile relationship with our API platform and give them all the confidence they need?” And the second question is, “How can we introduce new features while maintaining a predictable and adaptable API over time?” Like, let’s say you wanna offer dozens of new features over time, how are you gonna do that without developers renegotiating their contract with you?
So, let’s kick it off with the first one and see how we’ve been trying to address this challenge at Stripe. How do the developers most fundamentally interact the platform today? Well, at Stripe, we care deeply about consistency and attention to detail. So from day one, things like API, you know, errors, for instance, have been like a core part of the developer experience. We thought about, “How can we help developers anticipate their mistakes along the way?”
So in that case, for instance, let’s say I specify a wrong API key, Stripe will tell me, “Actually, you know what, like you just had…you just specified the wrong API key, but the object exists in the other mode.” So trying to anticipate those mistakes. Over time, we’ve become more rigorous and precise in our error code. We’ve revamped, for instance, all of them recently, so that developers have a better fluency in the conversation. And they can have, like, you know, the ability to handle programmatically all of these failures in their code base. And also, we go the extra mile in the docs, you know, providing small things like placing your API keys, and so on, in the docs. But we looked at the interfaces that developers really deal with. And one thing we’ve done over time was to expose like, complete request logs with all the params and all the body, you know, details of every request. And that’s pretty cool when you’re implementing Stripe because you can debug easily what’s going on. But that’s not quite enough because, you know, like Stripe, like many API providers is largely self-service.So people will just rely on Stripe and go live to production without really talking to us. But then how can you really instrument at scale what’s going on when you’re going live in production?
So these are all incremental changes. And we wanted to provide, like, a new space for developers to have all the tooling, and all the insights they needed when they were building on Stripe. So we shipped a few months ago, a new developer, a new set of tools in the dashboard of Stripe. And it’s kind of a single pane of glass, if you will, like single pane of glass experience for developers right in dashboard, where we put a lot of data and tools, front and centre so developers can really have all the information they need to make, like, efficient action and have, like, great insights into their integration. But let’s zoom in and dive into a couple of those things that we’re doing at the dashboard.
The first thing is we put best practices and recommendations right on top. So take a look at this one, for instance. We noticed that over the course of this app running in production, it sounds like one request failed because an API route was invalid in the past seven days. And this might be due to a null identifier, so like those very precise things, we’re trying to anticipate and put them front and centre for the developers because they might not have noticed over the course of running the app. So we’re trying to add more and more of those each case, and really providing more of those recommendations over time. Next, we regularly release new API version at Stripe. We have this solid foundation of, like, backwards compatibility, which lets us like iterate really quickly and cut API versions every time we need, so that the code written by developers will never break. But what’s interesting here is that we heard feedback, it was not always easy for developers to understand, like, what changed between versions.
And also they were not quite confident always to upgrade their API version, not knowing if something might break their integration. And we also wanted to let them do that over time. So with this new section around the versioning, what happens is, you can basically see the traffic in test mode or in live mode. And so you can slightly…slowly, but surely, upgrade your code base to the latest version, and then see the traffic and see if everything goes well, whether it’s in test mode and then when you’re ready to go live. And how do you know when you’re ready to go live? Well, the dashboard now provides also real-time insights into how people consume the API. And we think this is really important because you can now filter all your errors by endpoint, by type as well. And also instrument all the webhook response time that are coming back from your servers. And so that’s really helpful when you’re implementing Stripe because you can debug your request.
But when you’re running your business at scale on Stripe, then, like, every error that might occur, like, obviously, you would not be able to paginate through thousands of pages of logs. But now you have all these things, front and centre, and in this particular case, for instance, I can see there was a spike probably due to a bad deploy and a mistake I made. And I can just click here and see precisely what happened to fix the problem. So it’s the space for us to provide dedicated developer tooling. And, of course, this new developer dashboard does not obviate the core requirements of providing a specification for your API. So we also ship an OpenAPI spec, it’s open source on GitHub. And we think that’s really important to have, you know, a machine-readable backend, in addition to frontend experiences. Because this way, the more specific your API is, the more you can use tools from the ecosystem, including Postman, for instance, on the screen, and you can really understand the total shape of the API and what it’s capable of.
We also create a project on top of the OpenAPI spec that we call the Stripe Mock. And Stripe Mock is a server written in Go that anyone can install on their laptop, it’s open source. It consumes the OpenAPI spec, and essentially mimics what Stripe would do but right from your machine. And the primary use case for this is when you write test suites. Test suites can have like many, many calls, you know, to an API. And so running test suites if you have hundreds of API calls might take some time if you’re hitting the servers on the internet. So this time, with Stripe Mock, we think we have a great solution for, one, having those test suites running extremely fast on your local machines. And then, combine that with the developer dashboard and the frontend tooling, you have everything to monitor an instrument what’s happening when you’re deploying your code. So that’s how we’ve been thinking about the full-stack developer experiences and API for our first question.
Now, moving on to the second challenge. Like, if an API is kind of a contract that we’re establishing with users, how do we evolve this contract over time?
And as the world changes around this, how can we as an API provider continue to model the real world and evolve the API to address, like, new user needs? How you extend that contract, essentially. And, of course, we have this solid foundation that I mentioned, which is this, like, backwards compatibility on the API. But what if we wanna offer like dozens of new features, that’s gonna be extremely hard for developers to hit all those new endpoints and continually reconsider their contract with you. So when we launched Stripe in 2011, we had this good snippet on the homepage. We really wanted back then to already get across that developer experience really mattered to us. But there’s one big problem with this good snippet though, it’s built around credit cards. And sure, credit cards are the default here in the US but as you start thinking about bringing your business to more countries, this is not quite the case.
Let’s say you want to sell in China, you’ll need to ship out WeChat Pay and Alipay, and honestly, you don’t really have to go that far. If you look at Europe, for instance, in Germany, 20% of transactions online only happen with credit cards. All the rest, like, is basically a set of, like, bank debit scheme that are very popular and other payment methods there. Zooming out, the world is actually a pretty exotic place when it comes to online payments, only 55% of online transaction happen with cards. And that trend is accelerating, more and more payment methods are coming along. And consumers, you know, love them in different countries, and there’s less and less time for people to re-implement them. And they know, like, all our entrepreneurs and builders I’ve been talking to, they’re kind of aware already. They have like all these payment methods online, but they don’t really have, you know, the time to deal with that complexity. So at Stripe in 2010, that was the original transaction endpoint, a very clear abstraction, a few parameters, and amounts of currency and the card details. Synchronous, reusable, does not require authentication, that was pretty simple.
Well, then we wanted to accept in 2013 more payment methods including 3D secure for cards, and also Bitcoin and Alipay. And so we wrote, essentially, three bespoke custom endpoints for these payment methods. But then we realized that we were creating a very difficult precedent there because maintaining clean abstractions for 3, 5, 10, 20 payment methods was going to be extremely complex over time. And the other thing was, we realized that the amount of code we had to maintain was a good proxy to understand the amount of code users would have to maintain. So this was all not scalable and we went back to the drawing board. The challenge was, how can we build one common rail and build a universal API for all of these payment methods out there? And essentially, have these contracts that abstract away future optionality, future of payment methods. So we introduced the sources API to provide the necessary agility to actually address that problem and navigate global markets. So I’m not gonna dive into details of this but you can think of payment methods in the many different ways.
But essentially, when you start digging deeper, you can find like some unified framework to kind of categorize them, like, whether they’re like, customer created, customer completed, whether the business is initiating them, whether the funds are delayed, and so on, and so forth. So that’s how we kind of looked at the problem and decided to design these sources API. So let’s take the example now of iDEAL which is the most popular payment methods in the Netherlands. So that’s on the top, the first request you can see is the code you need to create a source of type iDEAL. So you pass type ideal, the amount of currency, in particular here we can specify the bank. But that’s pretty much it and you can create a charge with the source you obtain. But now, let’s say you wanna go to Germany, well, the only thing you have to change really is the type of the source. Now you can pass type SOFORT and if I actually go back to a previous slide, you can see what changed, like, only a couple parameters that you can have, like, one for the type and one optionally for the payment methods.
So that’s pretty awesome because you can have one integration path, one contract, essentially, to address all of these payment methods. And next, we thought, “Well, of course, we have this new backend foundation and backend API now. But how can we like provide, again, the frontend experiences the full-stack experiences to test those things?” Because, of course, like, you don’t really have an account with Alipay, an account with iDEAL to test and even the devices because sometimes you have a second factor device. So we designed test benches that kind of led developers understand, like every single possible case, simulate them and already have, like, all of these scenarios addressed to be confident when they go live. And then in the dashboard of Stripe, once again, now going live to a new country is essentially just one click of a button. If you want to enable Alipay, if you want to enable WeChat Pay, just one click and that’s how simple it should be. So with this, we’ve built Stripe to enable, like, a lot of currencies but also old payment methods now which is becoming an order of magnitude, less work, thanks to that unified rail for all developers to integrate.
So these are a few thoughts on how we think about APIs as contracts and how we optimize really developer experience for our users. And these are the kind of questions that me and my team at Stripe Developer Relations think about every day. We’re trying to address those questions every single time. And to answer these two. One is kind of, like, building tools to define both the backend and the frontend experiences. And the second is wherever possible as you’re building your APIs, try to see whether you can keep the number of contracts as small as possible. Can you like, essentially abstract problems at the right level? This is all about winning the hearts and minds of developers. So taking a step back and looking at where the industry is going, it’s pretty clear that developers are the new kingmakers now. Like, they are very much, like, the important decision makers in companies and they are creating things of great value with sometimes just a little bit of code.
So that’s where we arrived at: build tactile tools for developers, create the right API abstractions for them as early as you can. And last but not least, like maybe the most important, really engage with, like, authentic dialogue with your developers. Like, for instance, when you provide feedback to us in the dev dashboard, this is immediately piped to us and the engineers, so we can really engage every single day with developers. So with that, I think APIs are clearly the building blocks of the companies of the future. And we’re really hoping that we’re pushing what’s possible in terms of developer experiences and what they expect when they’re building on top of this API economy. So this all has to be renewed in a daily basis, we’re never done, so if you have any feedback, any questions, I’d love to answer them. And if you’re interested in building the commerce infrastructure of the internet, we also hiring at Stripe. So with that, thank you very much.
Jamie Wittenberg from Major League Hacking discusses the various ways in which your documentation can lose new developers in this talk from DevRelCon San Francisco 2019.
Write for us