This content initially started as a brain dump that was supposed to ship as a short Twitter thread, but based on this, I'm now shipping this as a blog post. It will probably turn into a mini-series of smaller posts like this.
Since leaving Stripe, I've received many questions from founders, operators, and investors about whether I could share some insights into the work we put into building Stripe's developer platform and API developer experience. In this post, I want to share a few learnings from some of the pieces we built over the years, and link to resources that might be valuable for others building their developer platforms.
In 2024, I often see companies providing public APIs focused on delivering excellent documentation and code-generated SDKs, fueled by the rise of DXI companies. However, to provide a truly great developer experience for APIs in 2024, there's more to it than meets the eye.
So here are a few insights and some of the things we built for @stripe's developer platform:
Foundation: First and foremost, a great API developer experience starts with a strong foundation: An intuitive API platform grounded in principles and predictable patterns across its surface area.
At Stripe, we spend a lot of time agonizing over patterns and consistency across the API to ensure developers have a consistent DX across products and abstractions.
With the rise of AI and agents, it will be increasingly important to have a strong API foundation based on predictable and consistent patterns easily digestible for systems. This may be more important than everything else. Time will tell.
API Review: To operationalize this, we introduced a forcing function called API Review, where every change that modifies Stripe’s API must pass a strict review process staffed by a cross-functional group of people who care about API design.
Naturally, it was challenging to manage as a centralized friction point for the company, particularly at scale with 1000s of engineers.
If I were to do things differently today, I would probably pivot the concept away from “review” to more of an education service that helps internal engineers develop excellent and consistent APIs.
Engineers aren't always great API/abstraction designers, but this skill can be learned with support and tools.
-> This should be a product. Let me know if you are building this!
My former colleague @cjav_dev has a great post on the API design process here: https://blog.postman.com/how-stripe-builds-apis/.
Abstraction ladders: Every API is an abstraction, and as APIs evolve, so does their abstraction ladder. Great abstractions enable developers to do powerful things with minimal effort, and great platforms reveal power and complexity as they progress through the abstraction ladder.
My former colleague, @sebasbensu, has a great blog post about API as ladders: https://blog.sbensu.com/posts/apis-as-ladders/
Consistency across abstractions: One of the most common mistakes I see among companies are inconsistencies between method names and return signatures across abstraction ladders like REST → Back-end SDK → React SDK.
It doesn't matter if you call GET request to retrieve or get in your SDKs. What matters is consistency all the way through.
Error messages: The difference between a good and a great error message can mean hours saved in debugging, so in addition to being rigorous on the error messages themselves, we also included two links directly to the request logs and the relevant doc page as part of the API response to enable better resource discoverability.
Request spell-checking: Building upon great error messages, a common mistake is getting a parameter name wrong, so why not do some spell-checking and help developers?
Notice the: Did you mean email?
Test-mode and instances: As developers build integrations with your platform, they will make a lot of requests, and a good portion of those will have errors as the developers learn your API. To make it easier to get rolling, we set the standard by introducing a test mode that enabled developers to test their integration with Stripe without messing up real data or moving real money.
Having a test mode is critical, and in this day and age, I consider the evolution of test-mode with multi-instance/environment support to be a table stakes in 2024.
Request logs: As developers make requests to your platform, they want to understand what’s happening with those requests. So, we offered Request Logs in our developer dashboard to enable developers to confirm that Stripe actually received requests and what we received.
Request logs are a very underrated feature and something most developer platforms lack.
Further, having request logs enables “inspectability” of any API request, an essential educational tool for developers, as they can learn how the platform works by inspecting requests and understated object models and relationships.
Example: Every API request made by the Stripe Dashboard shows up in request logs, enabling anyone to use the Dashboard UI and map it to the underlying API requests.
Integration insights: Building upon request logs and the concept of inspectability, we built Integration Insights, which would analyze API request errors and provide developers with actionable insights and tips on fixing their integration.
Developers would up/downvote insights, which helped our recommendation engine provide insights.
Integration builders: It's common to provide sample projects and code examples to help developers get started, but what developers really want is a more educational approach that can teach them core concepts while they see code.
So we introduced what we called integration builders, which takes an interactive approach to explain concepts while showing developers tangible sample code they can download and run.
The format has been vital in getting developers started even faster on Stripe. In particular, Stripe has scaled from indie hackers building in PHP to enterprise developers building in Java.
Integration with existing tools: Most developers don’t live inside your platform but in other tools and platforms. So, to meet developers where they are, we built tools like Stripe CLI and Stripe for VS Code, enabling developers to quickly test their webhooks, lint their code, and generate integrations with Stripe.
Thicker SDKs: As we went from handwritten SDKs to code-generated SDKs based upon our OpenAPI spec, we gained the ability to have always up-to-date SDKs and code examples in our docs. This also enabled us to provide static types for languages like TypeScript.
Most importantly, it enabled us to focus our investments on thicker SDKs for frameworks like React, where we could now provide more tailored experiences by building upon our code-generated baseline.
Lastly, while building supporting developer products and processes for our developer platform, nothing would beat the process of dogfooding our own products and abstractions through a process we called friction logging, where we all would try to use a new thing and document all the friction along the way.
Here is @dps sharing insights about friction logging to @lennysan:
If you've made it this far, I hope you enjoyed this little post. Let me know what else you find interesting, and I'll incorporate that into the next post.
As always, I regularly share thoughts and perspectives on developer experience and developer platforms, so follow me at @auchenberg.
Best, Kenneth