It’s hot to talk about how improving API User Experience can make end users happy. UX is important to consider with APIs and with any kind of development. But sometimes we forget about the middle men and women who are often the true intended audience and customers. When developing an application programming interface, or API, it is essential to keep developer experience or DX as a priority in everything we do.

What Is Developer Experience?

First, let’s look at user experience (UX) in general. UX considers the overall experience a person has with a mobile app or website. This attitude can be positive or negative given the value and ease of human-computer interactions.

Developer experience is an extension of UX that focuses on the developer, who can either be the intermediary or, as is the case with many APIs, the end user. Whether or not you focus on DX design, your developers are always experiencing your API, and that experience may either be positive or negative.

There’s no doubt that APIs are driving our mobile and integrated world. Apps and websites are looking to use APIs to attract customers and to scale rapidly. In this hectic process, API providers are unfortunately losing sight of quality developer experience.

Ronnie Mitra – DX Evangelist

One person has spent years trying to draw our attention to DX. Ronnie Mitra is the director of API design at the API Academy, which focuses on API design and implementation best practices. Talking about developers, Mitra writes, “If your API is poorly designed, poorly documented and poorly supported and they’re not required to use it, you can bet they won’t.” If we improve the experience developers have while working with APIs, Mitra argues this can dramatically improve usage rates. In this piece, we outline the ways Mitra and other API influencers have worked to do just that.

What Is A Bad API Developer Experience?

Mitra kicked off his talk at the Nordic APIs conference in Stockholm with a monotone stutter, staring at ugly Windows 95 slides with his back to the audience. The dynamic speaker did this to drive home how information, no matter how useful it is, won’t be consumed if the experience is not presented well, is not structured well, and is not interactive.

Should API Design Focus on Functionality, Usability, or Experience?

Mitra contends there are three often siloed concentrations of API design:

Functionality as a Design Factor: This was what followed in the time of service-oriented architecture; designing for the function and focusing on what activities and actions need to happen. What does the API do? Where is it located? How reliable is the implementation?

Usability as a Design Factor: This is the focus of most contemporary API design. “We used to be more service-centric and now we’re more developer-centric. We care about users,” he explained. However, he warns that “Usefulness still trumps usability. No matter how usable your product is, if it doesn’t do anything that anyone wants, no one will care.”

Experience as a Design Factor: How does the API make the developer feel? Mitra defines DX as the sum of all interactions between you and the developer, and how the developer feels about those interactions.

The interaction of all three combine to make (or break) the developer experience. Even though we are building software for other people to build software with, we are still building a line of communication— the human point of this abstract interaction. Mitra contends that in order to design for usability, providers first must understand their audience inside and out.

How to Measure API Usability

You might ask how one can measure something as intangible as human interaction and experience. To get there, you must first research your target developer to construct a persona for a typical consumer of each API. According to Mitra, it’s not the simple “Apple Genius profile” you usually imagine it to be.

Consider these questions that an API designer can try to answer in order to determine whether their API is usable, from the perspective of the developer:

• Task-Invocation Ratio: How many calls to the API does it take to accomplish each objective?
• Structure: What is the structure of the request and response? How deep does a developer have to go to get what they want?
• Navigation: How much noise is there? How difficult is it to move the data they want?
• Developer Stack Size: How many additional tools and libraries does a developer need to install in order to use your API?
• Time to First Call: How quickly can a new user make the first call to the API?
• Error Handling: What is the nature of the errors that are happening? How difficult are they to fix? Whose fault are they? Where are they happening?
• Vocabulary: What does a developer need to know in order to use your API easily?

These usability questions must then be applied to the personas you’ve established. Only then can you begin to develop answers to the subjective traits that make up experience such as engagement, pleasure, familiarity, and perception of trust and security. Statistics that measure usability paired with awareness of user experience combine in an attempt to quantify developer experience.

Use an API Audit to Enhance DX

Mitra suggests that business strategy and design goals that are responsive to developer experience are always going to be more successful than an API launched to market for public opinion.

Lead software engineer and integrator Raul Perez recommends performing an API audit before opening it up to the world’s developers. You must “eat your own dog food” by testing your API to find flaws before your user does. Perez gives us the steps to perform an internal API audit:

1. Go Beyond CRUD: Create, Read, Update, and Delete is a good start, but it’s inefficient alone. You need to work with multiple data sources at the same time, improving filtering and adding additional search functionality.
2. Multitask: Try to work with many items at once. If your API is slow or throttles (has an API rate limit), design it so that one call can return a list of items.
3. Filter Results: Consider how the consumer prefers their data to be structured. Think of common filters that a user may desire. Test them. Having filters for each resource can drastically reduce the number of results that the API will serve for the most common queries.
4. Be Sure to Include an API Search: While a filter can be limited, a search allows you to work with portions or with more than one of the values ​​of these fields at once. Perez believes that a searchable API is the epitome of a developer friendly API.

API Documentation Helps You Design and Develop With the User in Mind

For human-focused API documentation, Mitra argues that you must identify different levels of API reader expertise. This can range from a first time visitor curious about basic functionality, to a seasoned developer interested in the rationale behind design decisions, performance and scalability.

API documentation should be made accessible for these varying audiences in a consumable style with effective examples. It’s even been proven that proper API documentation ignites API adoption rates. So what makes for value-filled documentation?

1. Snippets: small piece of code or interaction offered to illustrate a concept described in text
2. Tutorials: step-by-step walkthrough of complex or popular tasks
3. Application: offering the source code of current API clients as example

Designing API-First Helps Keep Developer Experience First

The practice until now has been to design a website or application and then to build an API. One way of designing an API with the user in mind is by designing the API first.

The “API-first design approach helps a lot to internally structure your IT system and architecture, and also helps you to maintain your architecture better,” said Manfred Bortenschlager, API market development director at 3scale.net.

By eating your own dog food, organizations maximize API efficiency and continue to improve an API internally. About 12 years ago, Amazon Web Services, pioneers of the web API, made it so that internal business units could only communicate via API. This led to both better API developer experience and widespread innovation.

By defining the API first, you naturally guarantee a better developer experience, as everything you do will be built on top of it. Making an API available from the start can also act as an immediate added revenue source, a way to increase brand awareness and efficiency, and, like with AWS, a way to foster open innovation within your company and with your end user developers.

Conclusion

When designing an API, you must constantly remember that if your API is poorly designed, documented or supported, nobody will use it unless they are forced to.

Before designing a better developer experience, we must first answer:

1. Who are we designing it for?
2. Why we are designing it?
3. What are the constraints?

API design must focus on a blend of functionality, usability and developer experience. Usability must be measured via an API audit and then by tracking the actions your developer users are making. API-first design is one way in particular that you can focus on the developer experience from the ground up, since you play the role of the developer with every design action you take.

Mitra also advocates that maybe you should start going to developer conferences instead of user conferences in order to start connecting with your end users. Of course, at Nordic APIs, we think you should go to both! Continue this discussion at one of our upcoming events in Copenhagen, Munich, London and Seattle.

Now, tell us, how are you designing APIs with developer experience in mind?