API experience is the sum of everything a developer feels while working with your API, and it’s the thing that most determines whether they stay or leave. The experience isn’t the API itself — it’s the whole journey: discovering the API, understanding the documentation, getting a key, making the first call, hitting the first error, finding help, building the integration, and depending on it over time. Every one of those moments is a chance to delight a developer or to lose them, and the cumulative quality of those moments is the experience. I’ve spent fifteen years arguing that producers obsess over their API and neglect the experience, when the experience is where adoption is actually won or lost. The API is necessary. The experience is what makes it usable.
My very first writing on this, back in 2010, was about how to avoid frustrating your API developers — and frustration is the negative space of experience. The frustrations are mostly basic and mostly experiential: broken or incomplete documentation, no code samples, senseless rate limiting, no self-service registration, unreliability, restrictive terms, poor communication. I revisited the same theme in 2012, cataloging what drives me crazy when integrating with a new API, and the list barely changed. These aren’t deep technical failures; they’re experience failures — friction at the moments that matter. Every point of friction between “I’m curious” and “I made a successful call” is a place where the experience breaks and a developer walks away. Good experience is, at minimum, the systematic removal of that friction.
The conceptual shift that sharpened my thinking was moving from resources to experiences. I wrote in 2014 about evolving beyond just resources toward a more experience-based API design — the recognition that an API exposing raw CRUD operations on resources is not the same as an API that delivers a meaningful experience. The resource-based API makes the consumer do all the work of assembling resources into something useful. The experience-based API anticipates what the consumer is actually trying to accomplish and shapes the interface around that outcome. By 2024 I’d refined this into a progression — API resources to capabilities to experiences — where resources are the raw CRUD, capabilities are business-aligned units of what you can do, and experiences are the meaningful, friction-free journeys that rise above the noise. The best APIs aren’t just well-designed resources; they’re designed around the experience the consumer needs to have.
The most important reframe I’ve made recently is to talk about human experiences instead of the API lifecycle. I wrote in 2024 that we should stop talking in abstract lifecycle terms and start naming the actual human experiences: onboarding, reliability, integration, trust, access, communication, change, consistency, quality, money, security, simplicity. These are what developers actually experience — not “the design stage” or “the management stage,” but whether onboarding was smooth, whether the API was reliable, whether they could trust it, whether changes were communicated. I even mapped these twelve human experiences to governance policies and rules, because the experiences a developer has are downstream of the decisions a provider makes. Governance, documentation, design, support — all of it exists to produce a good human experience, and naming the experiences directly keeps the focus on the human rather than the abstraction.
What makes some APIs charismatic is, ultimately, an experience question. I wrote in 2024 about what makes APIs like Stripe and Twilio charismatic, and the answer is the experience they deliver: simplicity, a real human presence in the community, exceptional documentation, good SDKs, and genuine usefulness. Charisma isn’t a feature you can add; it’s the emergent quality of an experience that consistently respects and delights the developer. Simplicity is central to it — I wrote in 2025 that API simplicity matters in this moment, because simplicity takes real work and pays dividends in experience, while vendor-driven complexity degrades it. The charismatic APIs feel simple, even when what they do is complex, because someone did the hard work of absorbing the complexity on the producer side rather than exporting it to the consumer.
The frontier of experience is where it meets investment and economics, and I think the industry is finally catching up. I wrote in 2026 that the next wave of API investment will be all about experience — meaning the organizations that have already done the foundational work of consistent, reliable, well-governed APIs are now competing on experience, because that’s what’s left to differentiate on. The intersection of static docs, interactive docs, explorers, and clients that I mapped in 2025 is really an experience map — these are the surfaces where the developer experience happens, and blending them well is how you deliver a continuous, friction-free journey. Experience is becoming the competitive battleground precisely because the baseline technical work has matured, and what distinguishes a great API program from an adequate one is no longer whether the API works but whether working with it is a genuinely good experience. That’s the thing producers most underinvest in, and the thing consumers most remember.
References
- How To Avoid Frustrating Your API Developers
- What Drives Me Crazy When Integrating With A New API
- Evolving Beyond Just Resources Towards A More Experience-Based API Design
- Resource-Based API Monetization vs Experience-Based API Monetization
- What Makes Charismatic APIs
- API Resource, Capabilities, And Experiences
- Mapping API Experiences To API Rules Using API Policies
- Talking About Human Experiences Instead Of The API Lifecycle
- The Intersection Of Static Docs, Interactive Docs, Explorer, And API Clients
- API Simplicity Matters In This Moment
- The Next Wave Of API Investments Will Be All About Experience
