When it comes to creating and maintaining a thriving developer community for your API, developer experience is the foundation you’ll be building on. With thousands of APIs to choose from, the well-documented API that makes it easier for developers to get up and running has a competitive edge. But what exactly constitutes developer experience? Why does it matter? And how exactly can you improve yours?
What we mean when we talk about DX 💬
If you’re familiar with the tenets of user experience (UX), then you’ve got a head start on understanding developer experience (DX). When you’re building, maintaining, and managing an API, you have users like any other SaaS product — they just happen to be developers! Consequently, UX best practices around crafting great onboarding experiences, reducing product friction, and driving engagement to help users realize value apply to APIs as well.
Much like when considering user experience, empathy is a key factor. Put yourself in the shoes of a developer getting started with your API: someone who doesn’t know which endpoints to use first, how to construct the request payloads, or even how to set up authentication. They want to know the best approach for working with your API and how to make their first successful API call as quickly and easily as possible.
In the past, the conversation around APIs has largely centered on performance: design efficiencies, uptime, latency, and so on. These aspects are critically important for API teams to manage closely (you can’t have a great DX without a well-designed, reliable API!), but they’re not enough on their own. Even the best API will be painful to use without comprehensive, easy-to-navigate documentation, helpful code samples, and testing tools that give new developers a quick on-ramp to getting started. That’s what we’re focused on here at ReadMe: enabling you to build the best possible developer experience for your API 🛠
Why great DX is a must-have, not a nice-to-have 🚨
DX is a broad term that can cover a number of different interactions, and it can be hard to quantify — and thus measure ROI and justify resourcing for. Because of this, it’s tempting to let it fall by the wayside, or assume that it will take care of itself naturally as you progress through other aspects of building and maintaining your API.
However, just like UX, you need to actively center DX and improve it over time as you manage your API. No matter what industry you’re in, developers likely have options when it comes to what API they choose to work with. All other things being equal, the API that’s well-documented and easy to use is the one they’re most likely to choose: that’s where developer experience comes in. This is your chance to stand out in a sea of competition, bringing more users your way.
Let’s talk through an example. A company is evaluating a new customer support tool (let’s call it Owldesk!). An engineer from their internal tools team is responsible for assessing whether they can build the custom automations their support team needs using the Owldesk API. Here's a look at how Owldesk's DX choices can make or break that engineer's experience at every step:
- ✅ Comprehensive API documentation with built-in search to quickly get them where they need to go
- ❌ An API reference without additional guides or tutorials for context on use cases and best practices
- ✅ Step-by-step recipes and code samples to give them a jumpstart on common Owldesk integrations and automations
- ❌ Outdated, inaccurate, or nonexistent sample code requiring them to start from scratch, even for a popular use case
- ✅ Automatically surfacing Owldesk API keys to save them time tracking them down in their account
- ❌ Convoluted instructions for how to get API keys from within Owldesk before coming back to the docs
- ✅ A real-time record of API logs to help them troubleshoot issues with their Owldesk integration and easily get help from Owldesk support
- ❌ No visibility into API logs to diagnose an issue quickly — and Owldesk's support team doesn't have visibility to help dig in either
- ✅ A well-maintained Changelog sharing the latest updates and any version deprecation timelines
- ❌ No information about when certain API versions are being deprecated or new features to use
Do any of those "❌" scenarios sound familiar? If they do, you’re not alone. Many API teams simply haven’t the resources, time, or tools to invest in crafting those “✅” experiences, leaving developers to fend for themselves when it comes to using their API. In our example, hurdles like these and the engineer’s overall experience with the API could be the deciding factor in the company’s decision to go with Owldesk — or with another solution that’s easier to build on.
How to improve your DX 🚀
So you want to improve your DX. What’s next?
We’d recommend thinking of your API like other software products you’ve used or worked on. What are the lifecycle steps you go through as a user, or focus on as a product team? We model our DX approach on those same steps, and it’s a helpful way to break down the challenge into manageable parts:
- Evaluation & onboarding 🤔 Help users understand what’s possible with your API and enable them to make a successful first API call as quickly as possible
- Engagement & support ❤️ Empower users to build the solution they were looking for with your API and debug issues when they (inevitably!) run into an unexpected roadblock
- Retention & growth 📈 Drive adoption of new API features, increase usage over time, and ensure a smooth transition for users to new API versions or off deprecated endpoints
We’ll walk you through these essential pillars to building a great developer experience for your API. Some of our recommendations are uniquely possible with ReadMe (we’re obviously biased!), but many of them can be applied no matter what tools you’re using to manage documentation or build a developer hub.
Evaluation & onboarding 🤔
First impressions matter, and people form them quickly: typically in less than a second. Having a well-designed, clearly-branded hub tells developers that they’re in the right place and shows them where to go next.
We’ve said it before, and we’ll say it again: it doesn’t matter how well your API works if developers can’t figure out how to use it. It’s crucial to give developers a centralized place to explore API use cases, see helpful examples and sample code, and review guides that walk through what’s possible with your API. A good developer experience comes from useful documentation, it’s true — but if it’s not easy to search and navigate, they can’t very well learn about your API. The need for that unified hub is why ReadMe brings all those resources together in one place: long-form guides, your API reference, interactive recipes, and the ability to try out your API without leaving the docs.
This is why we’ve created ReadMe with features like Recipes and Try It, which let users see how your API actually works in real time. Recipes are an easy way to walk developers through code samples, highlight what’s possible with your API, and showcase best use-cases. Once they have an idea in mind, the “Try It!” button in your API reference lets users run requests directly from their browser and see the real-time response from your API.
And in the near future, ReadMe will support personalized “Getting Started” and “Authentication” pages, which work together with Variables to create a customized page for each new user that walks them through their first call. All of these pieces work together to create a developer experience that’s customized to fit their needs and designed to get them actually using your API as quickly as possible.
Engagement & support ❤️
Keeping developers engaged and motivated to use your API means minimizing frustration points. Having a robust search functionality sounds like an extremely basic feature — but it’s vital to making sure users can find the information they want when they want it. Make sure to test your search functionality using natural language and keep an eye on what keywords people are using, so you can make it easy to find the appropriate troubleshooting resources.
Developers should also be able to find their API logs quickly to help them debug issues, and ideally those logs will be viewable by the developer and the support team, so they can better communicate about and resolve issues. These may seem like small details, but when a user is already frustrated or confused, it’s important to get them the information they need ASAP, so they can stop feeling that way and get back to building cool things with your API. Remember: you want to create a developer experience that makes them feel competent, not confused.
If you have the time and resources to manage it, adding a support forum is a great way for developers to ask questions and get answers from your team, as well as each other. It can give them insight into what other folks are doing with your API — and might even spark some ideas for new integrations or functionality they’d like to build themselves!
The only thing to keep in mind is that it’s better to have no support forum than have a badly-maintained support forum, whether “badly-maintained” means it’s difficult to use or that user posts go weeks without getting answers from your team. If you’re unsure about whether the resources exist to maintain a more ambitious project, start small with other interactive doc features, like comments and suggestions.
Retention & growth 📈
When working on your DX approach, it’s important to think about the developer community forming around your API and how your team can interact with the community as a whole, in addition to troubleshooting with individual developers.
For example, keeping users updated about upcoming changes, offering versioning support, and creating detailed changelog posts for updates can be the difference between the user having a seamless upgrade to the latest API version and a DX nightmare. A community-focused approach means making it easy to get feedback from developers, whether it’s a simple thumbs up/down on a page or the ability to add comments and suggest edits to existing documents.
Your API’s usage metrics are also a great source of insight for how to invest in your API over time. Being able to see what your most-used endpoints are makes it easier to understand your users (and how they’re using your API), and metrics can also show you where users are getting stuck or what the most common errors are. All of this data, combined with direct feedback from developers, is key in creating a strategy for improving your API over time and figuring out which updates to prioritize over others.
Doing a regular metrics audit (whether it’s quarterly, monthly, or on a different schedule that works for you and your team) is a great way to pull out some of these insights. Of course, the specifics of what you’re tracking will depend on your current priorities. But in general, looking at user-focused success metrics like new user adoption, error rates, and drops in call volume can be particularly useful when seeking to understand how DX decisions are impacting your users.
Ready to get started?
Prioritizing DX can make the difference between having an API that people want to use — and a thriving developer community that goes with it! — or struggling to retain developers as users.
If you want to see how ReadMe can help you improve your developer experience, we’d love to show you! You can sign up for a free trial any time, or if you’re interested in ReadMe Enterprise, you can get in touch with our team here to request an Enterprise demo. We can’t wait to see what you build 🥳
