API Experience

I spend most of my working life either designing APIs or helping teams untangle the ones they already have, and I have come to think that the thing which decides whether an API succeeds is rarely the thing teams spend their time arguing about. It is not the framework. It is not REST versus GraphQL. It is how it feels to integrate with.

So let me ask the uncomfortable question: is API Experience quietly affecting adoption of your API? With APIs being the backbone of today’s internet, isn’t it time you paid attention to it, and to how you could reduce the friction and frustration that costs you users?

Before we can talk about API Experience, we need to talk about Developer Experience. Let’s start there:

Developer experience examines how people, processes, and tools affect developers’ ability to work efficiently.

GitHub Blog

Developer Experience is all about making tools and processes for developers easier and more enjoyable to use. It makes sure things are simpler and easier to build, a great DX ensures that developers can create software with less frustration and friction. It is all about smooth workflows, good documentation, and more intuitive tools that will help developers to do their best work.

API Experience is somewhat similar. Shortened to API Ex - it is a term that describes the ease of integration with your API. A positive API Experience will suggest that integrating with your API is relatively straightforward, even a pleasure, reducing the burden to a development team. This usually means that your API is well-documented, user/developer-friendly, and designed with the developer in mind. On the other hand though, a negative API Experience indicates that the API is cumbersome to use, poorly documented if at all, or becomes a burden to a development team to rely on.

The quality of your API is seen by developers as an extension of that experience. It affects the speed and efficiency of working with your API, which in turn affects project timelines. So it is worth considering deliberately, and worth improving continually with feedback from the people actually integrating.

Here is the part I wish more teams accepted: nobody ships an API with a great API Experience on day one. You need the feedback, and you need to feel the integration pains across a lot of different use cases before you find the balance. There is no magic formula. It is trial, error, and above all understanding the developers using your API and why they came to it.

That understanding is what lets you answer the questions that actually matter. Is documentation more important than being able to filter and sort a collection? Is strong error messaging more important than speed and caching? I cannot answer those for you, and neither can a blog post - they depend entirely on who is integrating and what they are trying to get done.

What I will say is this. Much like User Experience decides whether people stay with your web or mobile app, API Experience decides whether developers stay with your API. Understanding the frustrations and the journey a developer goes on is not a nice-to-have. A bad API Experience is the fastest way I know to lose a customer to a competitor who simply made integration easier.