The Components of A Developer Experience

Freshness Warning
This blog post is over 2 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

The Trap of The Sales-Led Product (Dec 10)
It’s not a winning way to build a product company.
The Hidden Cost of Custom Customer Features (Dec 7)
One-off features will cost you more than you think and make your customers unhappy.
Domain expertise in Product Management (Nov 16)
When you're hiring software product managers, hire for product management skills. Looking for domain experts will reduce the pool of people you can hire and might just be worse for your product.
Strategy Means Saying No (Oct 27)
An oft-overlooked aspect of strategy is to define what you are not doing. There are lots of adjacent problems you can attack. Strategy means defining which ones you will ignore.
Understanding vision, strategy, and execution (Oct 24)
Vision is what you're trying to do. Strategy is broad strokes on how you'll get there. Execution is the tasks you complete to complete the strategy.
How to advance your Product Market Fit KPI (Oct 21)
Finding the gaps in your product that will unlock the next round of growth.
Developer Relations as Developer Success (Oct 19)
Outreach, marketing, and developer evangelism are a part of Developer Relations. But the companies that are most successful with developers spend most of their time on something else.
Developer Experience Principle 6: Easy to Maintain (Oct 17)
Keeping your product Easy to Maintain will improve the lives of your team and your customers. It will help keep your docs up to date. Your SDKs and APIs will be released in sync. Your tooling and overall experience will shine.


What I'm Reading


Adam Kalsey

+1 916 600 2497


Public Key

© 1999-2023 Adam Kalsey.