Software Engineering
The Components of A Developer Experience
Freshness Warning
This blog post is over 4 years old. It's possible that the information you read below isn't current and the links no longer work.
19 Sep 2020
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?
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
- Principles of Developer Experience: An Introduction
- The Components of A Developer Experience (You Are Here)
- Principle 1: Easy to Understand
- Principle 2: Easy to Use
- Principle 3: Easy to Build
- Principle 4: Easy to Get Help
- Principle 5: Easy to Trust
- Principle 6: Easy to Maintain