Need someone to lead product management at your software company? I create software for people that create software and I'm looking for my next opportunity. Check out my resume and get in touch.

The Components of A Developer Experience

Freshness Warning
This blog post is over 3 years old. It's possible that the information you read below isn't current and the links no longer work.

You’ve built an API or other developer tool but no one’s using it. People find it, but then don’t adopt it. That’s because you forgot the human element of the API: the Developer Experience.

How do you build a great developer experience? What things beyond the API do you need to design, build, and maintain? The best way to think about this is to think of your API as a product.

You wouldn’t build a product and then put no thought at all into how you take it to market, how you support it, or how people will buy it. But that’s exactly what happens with most developer tools and APIs. Someone builds it, writes some quick documentation, and publishes it to the world. That’s as far as it goes, and the API never becomes the raging success it could have been.

What do you need to create to build an experience that developers will love?

Vintage Fan Disassembly

Start with the API. A well-designed API is the foundation you must start with. No matter how good the rest of the experience is, developers won’t adopt your API unless it is well-crafted and easy to use, understand, and build on. If you need help with this, there’s plenty of articles out there about great API design. Study the APIs you love to use. What makes them great? If the developer can’t understand what an API call does by reading the plaintext API request and response, you probably don’t have a great API yet. The biggest mistakes that are repeatedly made in API design are in error handling, authentication, and consistency. Focus on doing well in these areas and you’re already ahead of the game.

But the API is just the product - what do you need to put around the product to make it a success?

How does a developer find your API? And when they do, how do they know what it does, if it’s going to be useful to them, and if they can afford to use it? Discovery is the first part of your developer experience that most developers will use. A developer that finds your tool needs to understand if it’s fit for their purpose. Right up front, you need to describe what your API is good for, not in vague, corporate-speak marketing terms, but using plain language.

Once a developer has decided to try your product, how do they get Support when they need to ask a question? Whether you provide an email address to ask you questions, a forum where they can ask other users, or expect them to fend for themselves on Stack Overflow, the support expectations should be explicit.

Don’t ship without giving developers a way to Try and Test your API. Depending on what your API needs and how it works this might be as simple as an API key or as complicated as a sandbox with mock data they can interact with. It’s best if the trial can be free. It’s hard to get a developer to pay to see if your API suits their needs. But even if your API product requires expensive long term contracts, the more you can reduce friction the better.

Your Documentation and Samples are more than just an API reference guide. Successful API products provide Quick Start Guides designed to show how to get up and running with various API features. They include in-depth tutorials on building real-world applications. They have recipes that show the right way to implement common use cases. And they do it all in several different programming languages.

The very best API products give developers a host of Tools and Downloads to make their development experience easier. The starting point of this is often a helper library, but other tooling can be useful. Some products include mock APIs for automated testing, command-line tooling, or even syntax and documentation plugins for popular IDEs.

Not all APIs need a Developer Portal but it’s the rare product that you couldn’t improve by adding one. Giving a developer a place to manage their API keys, see their logs, or view their support requests can help most API products. More advanced portals can contain interactive debuggers, configuration tools, and payment options.

And finally, no developer experience is complete without information that helps them Trust your API. Showing a developer uptime and past incidents can help them trust the reliability of your cloud API. And although it sounds counterintuitive, showing them security incidents and fixes helps them trust that your product is secure and has an active security response plan.

All these tools and information are the necessary components to build an API that developers enjoy using. These components help them decide if your API is right for them and help grow their usage. They make your API a well-rounded product.

More about the Six Principles of Developer Experience

Recently Written

Too Big To Fail (Apr 9)
When a company piles resources on a new product idea, it doesn't have room to fail. That keeps it from succeeding.
Go small (Apr 4)
The strengths of a large organization are the opposite of what makes innovation work. Starting something new requires that you start with a small team.
Start with a Belief (Apr 1)
You can't use data to build products unless you start with a hypothesis.
Mastery doesn’t come from perfect planning (Dec 21)
In a ceramics class, one group focused on a single perfect dish, while another made many with no quality focus. The result? A lesson in the value of practice over perfection.
The Dark Side of Input Metrics (Nov 27)
Using input metrics in the wrong way can cause unexpected behaviors, stifled creativity, and micromanagement.
Reframe How You Think About Users of your Internal Platform (Nov 13)
Changing from "Customers" to "Partners" will give you a better perspective on internal product development.
Measuring Feature success (Oct 17)
You're building features to solve problems. If you don't know what success looks like, how did you decide on that feature at all?
How I use OKRs (Oct 13)
A description of how I use OKRs to guide a team, written so I can send to future teams.


What I'm Reading


Adam Kalsey

+1 916 600 2497


Public Key

© 1999-2024 Adam Kalsey.