Designing great API developer experiences – Part 1

Learn what an API portal and developer API portals are and how to create the best developer experience for your partners and clients.

Matthias Biehl Matthias Biehl

In their digital transformation initiatives, more and more organizations are becoming API providers and want to boost the usage of their APIs among developers.

But focusing only on the functional aspects of the API is a common mistake – let me show you how to avoid it.

The functional aspects of APIs are important: A good API enables developers to complete their tasks faster, deliver the apps faster and reduce the overall development costs. However, as an API provider you should not only focus on the functional aspects of the API.

A great API needs to be complemented by a great developer experience – the experience a developer has when using the API. It is important since developers are the customers of the API products and have significant influence on the buying process of APIs.

Most organizations have learned to value the deliberate design of end-user experiences in mobile apps and websites, but they may be missing out by not applying the same concepts of user experience design on their API products. For some organizations, developer experience (DX) is a new concept that is hard to grasp.

Why focus on API developers?

You may have many questions, such as: Why should you focus on developers? Why do they need an experience? What kind of experience do developers need and how do you create it?

In most cases, APIs are not offered to the end-users of a your company’s products, but to your partners and developers. When they want to use the API, they are often required to take the “shabby supplier’s entrance” instead of the welcoming front door. This means developers often have a hard time finding the information they need about an API.

Many of their questions remain unanswered, such as: What does this error code mean? How does authentication & authorization work? Or, how can I test the API and what do I need to do to get access to the API on production?  

This is frustrating for developers – and not a good overall experience. Developers have often been treated like a second-class citizens. Why should you change that? Just because you empathize with the poor developers? Yes. But there is even a business reason for it.

Developer experience (DX) is good for business

Developers have choices when it comes to using commoditized APIs, and can select amongst a growing number of API suppliers. And when it comes to buying decisions about APIs, the voice of the developers is increasingly heard within their organization. Developers will naturally choose APIs with a great DX, as it makes their lives easy. A good DX and a good API will allow developers to complete their tasks faster, deliver the apps faster and thus reduce the overall development costs. Faster time to market and reduced costs are appreciated by the business. So business will go along with the developer’s recommendation for which API to buy.

The pattern is “Developer tries – business buys.” If developers do not like the API or the DX of the API, this API will not even get shortlisted. What will get shortlisted, are APIs with a great DX. The business – or economic buyer of the API will buy an API from this shortlist, that has first passed the filter of the developers. 

As an API provider, you need to use this knowledge. Developers have significant influence in the choice of APIs. Investing in the developer experience, i.e. in the API portal or the consistency of your API portfolio contributes to the success of your API initiative.

In the next part of this blog series, I will talk about how to design great developer experiences using the design-thinking framework.

If you want to learn more, make sure your watch the full video below on creating great developer experiences.

Related post: 

Part 2: