APIs for humans: The rise of developer experience (DX)

User Experience (UX) is a top priority for many consumer-facing software companies. The art of simplifying complex interactions into meaningful user experiences is an important competitive advantage for technology companies.

But what if your product is an API and your end-users are developers? How do you design a good experience for them?

Designing an API that achieves your business goals means focusing on the Developer Experience (DX). The way to do that is by using empathy to understand your audience.

What is DX exactly?

Generally speaking, DX is about how developers feel while using your API – it’s emotive. It’s the aggregate of all the experiences a developer has when interacting with your API. This is typically not something we as an industry talk about when building products that are focused on developers.

We would rather talk about things that are more concrete: performance, scalability, etc.

We generally expect developers to be intelligent therefore we don’t go out of our way to ensure their experience is great. As we start moving toward APIs as the status quo, our industry is slowly starting to realize the value of DX.

Experience matters

DX is essentially the sum of the experiences using your API. If many of those experiences were difficult or just annoying, your users are going to have a bad experience. They won’t want to use your product. They’ll complain about your API to their friends. Even worse, if your competitors have a better DX, they will have a huge incentive to switch.

On the other hand, if your competitors clearly haven’t worked on the developer experience, this can give your organization a great opportunity to attract more users. If two competitors offer a similar API but one of them is developer friendly, the DX focused company has a huge competitive advantage.

Additionally, developer time is limited and can easily be stretched too thin – your API should not take up so much of their time or mental abilities to understand and implement. Having a great DX is key to creating an API that helps meet your business goals as well as your users goals.

That being said, DX is not a panacea – it’s not the only thing that will make your API successful. Functionality beats usability almost every time. If you’re not offering something developers want, no amount of DX will help. But if you and your competitors are offering something developers want, DX can make a crucial difference.

Empathy as a guiding DX principle

To deliver an effective API with an excellent developer experience, API designers need to understand the value of empathy. While designing an API with empathy sounds simple on the surface, it’s surprisingly difficult to operationalize for a number of reasons.

First of all, empathy is often a misunderstood concept. Generally speaking, empathy is the ability to understand another’s emotional state. It requires more than imagining what it would be like for you to be in someone else’s shoes. Empathy is understanding what it’s like for another person to be in their own shoes. How you would respond to a given situation can be very different from how another person would respond to the same situation.

For example, if you’re a developer or product manager working on an API, you’re going to be intimately familiar with how that API works. You would understand all the design decisions, know all the quirks, have become accustomed to the pain points, and know where all the edge cases are.

But a developer outside of your organization is unlikely to be as familiar with your API as you are – what you take as a matter-of-course is completely new to them. Usability is key to that kind of person.

At HelloSign, we believe so strongly in empathy we made it one of our core values.

Make your users awesome

We as API designers want to build APIs with great functionality and usability in order to foster a positive emotional response for our users. That said, what exactly do we want the users of our API to feel? What kind of experience are we trying to create and what kind of emotional response are we aiming for?

Most companies don’t ask these questions because the answer seems obvious: we want users to love our company and our products. There’s a huge problem with this line of thinking, which is most users couldn’t care less about our companies or our products. Users are surrounded by companies and products – why should they feel differently about your API?

Users of our API are people, and people are generally preoccupied with themselves. Therefore, we want to build and design APIs that make them feel awesome. They will want to build an awesome feature that they can show off to their friends and their boss in a short amount of time. They want to feel like geniuses. Therefore, we as API designers should do everything we can to make an API that makes them feel that way.

We don’t want to build an API that makes your users feel unintelligent because they can’t figure it out easily.

An effective API must be a combination of awesome functionality and awesome usability. Developers are under tremendous pressure to deliver features – by doing everything possible to help them do that we can make sure they feel good about their integration and your API.

Creating an empathic API

Using empathy as our guiding DX principle, we can deduce some implementation details. They may differ depending on the circumstances of individual organizations, but there are some things API designers can generally do to help create an effective API.

Communication: Make it easy to understand

As a good start, having clear and up to date documentation is a great way for your users to understand how to use your API. Users are going to spend a fair amount of time reading the documentation, therefore it should be considered part of the product.

Stripe does a really great job at providing API documentation; they have a solid introduction with logically organized sections, followed by a clear API reference. As you scroll down the selection on the left, the menu sidebar updates as well, letting you know exactly where you are in the documentation. They even have a fixed half-header where you can quickly change the language of the documentation, making it even easier to interact with the documentation.

In addition to API documentation, having a comprehensive collection of “Getting Started” guides are a place for developers to go and quickly get up to speed with what they need to know.

Make your API easier to use

It’s easier to understand an API if it’s easy to use. API designers should do as much as they can to make the barrier to entry for their API as low as possible, thereby increasing adoption rates and overall user satisfaction. Consider reducing non-coding setup required as much as possible; things like creating accounts, apps, signing up for a paid plan, or talking to a sales person should be kept at a minimum or eliminated.

Additionally, consider providing SDKs for your target audience. You still want to allow developers to interact with your API with just HTTP, but providing SDKs in multiple languages allows your developers to easily interact with your API.

A large percentage of developers are expecting SDKs in their preferred programming language. We at HelloSign have invested a lot in SDK’s – we have them in Ruby, Python, NodeJS, PHP, and Java. Providing a convenient SDK to developers creates a great incentive to use your API over your competitors.

That said, there is an incurred cost of having to maintain multiple SDKs in languages your team is not familiar with, so starting with the language your team is comfortable with is probably a good starting point for your company.

If you’re targeting startups, there’s a high probability they will be using JavaScript or Ruby, therefore creating SDKs in those languages can capture a large percentage of those users. If you’re specifically targeting enterprise customers, you may consider supporting official SDKs in .NET, and Java.

Another strategy for managing SDK maintenance is open sourcing your SDKs and allowing the community to submit pull requests. This allows your users to change the SDKs to suit their needs, or find and fix bugs if they arise. This is also a great way to get user feedback about the usability of your SDKs.

Make your API easy to debug

Things are inevitably going to go wrong and bugs are the norm when writing software. However, debugging an API in production can be especially painful due to the asynchronous nature of APIs. It’s very difficult to track down exactly what went wrong, whether it was on the user’s end or the API’s end.

Debugging an API shouldn’t be difficult. The solution is providing an API dashboard. A dashboard is part of any well designed API, where a developer can go and see all their requests and callbacks, and know at a glance exactly what went wrong. This saves a ton of time for developers. It’s almost a no-brainer.

Here’s an example of the HelloSign API Dashboard:

Read more about API Dashboards: Why Every API Needs A Dashboard

Make it easy to get help

Sometimes a user will come across a problem they can’t resolve on their own. In those cases, it would be great if they could reach out to your organization for assistance. Have a dedicated API Support team but if this is not possible, have your developers take turns handling API Support.

This serves the dual purpose of helping out your users and helping cement empathy for users among your development team. Keep an eye on GitHub issues and StackOverflow questions. Make it easy for developers to reach you through public Slack and HipChat rooms, as well as an IRC channel.

Don’t market to your developer users. Help them and contribute to the community

While not directly applicable to an API, marketing shapes how your users feel about your product. Developers hate traditional marketing – it generally insults them. Respect the intelligence of your developer users and avoid traditional marketing where it doesn’t make sense. Instead, help solve their problems and do what you can to contribute to the community.

A developer is an expert at consuming and understanding information. They’re well read and educated. They will know when you’re marketing to them and ignore all your marketing campaigns. If anything, it will harm your brand and your developer experience.

It also makes you looks suspicious – as far as a developer is concerned, who you are and what your products are speak for themselves. They are intelligent enough to figure out what is the best fit for them and their company. If you need to market to developers, they’re just going to suspect it’s compensating for a lackluster product.

Instead, look to contribute to the developer community and create a community of your own. Deliver as much useful content on your blog, hire advocates/evangelists to teach courses and give talks at meetups, and make contributions to open source. The same kinds of things you would do to attract developers to work for your company are the same things you should do to make developers want to work with you API.

Why companies fail to create empathic APIs

Designing an API is simple. A competent developer can design an API under an hour. Designing an empathic API is much more difficult. It requires a change in attitude towards users and in some ways, toward our own employees.

Conway’s Law

Conway’s Law states “organizations which design systems … are constrained to produce designs which are copies of the communication structures of these organizations”. Conway’s Law is normally referenced when talking about software architecture, but it’s just as applicable to API design. If an organization doesn’t internalize empathy as part of their culture, they’re less likely to empathize with their users. Lack of empathy within the organization is going to show in what it produces, including the API design.

Too familiar with API

Lack of empathy can also be an innocent result of familiarity with the API. This naturally occurs over time – a team will become very familiar with the API and might fail to see how others cannot intuit how the API works. Because of that, they can become resistant to criticism.

After all, if the team finds the API intuitive, it’s likely they will assume that either users lack their level of intelligent or that confusion is just an outlier. Being cognizant of this tendency and taking measures to empathize with users can help alleviate this potential problem.

Fail to solicit feedback

Lastly, a company may fail to provide an empathic API because they don’t solicit and prioritize user feedback. It’s vital for understanding your customers needs and pain points to ask for and respond to feedback. Users will not give you much feedback unless you explicitly ask for it.  Find ways to get feedback from your users and make sure there are mechanisms in place within the organization to ensure feedback is thought about and acted upon if appropriate.

Conclusion

Here at HelloSign we’ve put a lot of effort in creating an empathic culture which shows in our products.

➤ This article first appeared on HelloSign

Read next: 4 UX habits for improving interaction design