The User Experience of APIs

  • Benoît Pointet

After having read how some people can hold and transmit the terrible misconception that designing APIs has nothing to do with designing great experiences, I felt one could provide a few insights into the benefits of shaping an API around its consumers – the developers and the machines – as much as around the data.

After having read how some people can hold and transmit the terrible misconception that designing APIs has nothing to do with designing great experiences, I felt one could provide a few insights into the benefits of shaping an API around its consumers – the developers and the machines – as much as around the data.

APIs are for humans what websites are for machines

Like a website, a point-of-sale, …, a web API is just another service touchpoint. And as any web-based touchpoint nowadays, its audience is part humans, part machines.

Interestingly, the audience and content structures of an API are diametrically opposed to those of a website.

A website is explored by machines – called bots – who precede and orient a (hopefully) larger number of human visits. A website main content targets its main human audience, while its metadata targets its secondary audience: machines.

For an API, it's just the opposite.

An API is explored by humans – developers, mostly – who precede and orient a larger number of machine visits. An API main content targets its main machine audience, while its metadata targets its secondary audience: humans.

Design APIs with the developer experience in mind

So how can user experience design help with APIs? Think of it as a kind of “Developers Optimization” (like SEO helps machines on your website): by lowering the barrier for the developers to understand and code with your API, you raise chances of adoption, success and reuse.

Suppose that you work for some bank and are designing some kind of money API. The information and action points that this API will convey belong to the banking business domain, maybe evenmore specifically to the field of mortgages, maybe even to a specific understanding of that specific field within that specific domain, an understanding that only exists within your bank.

Yet this future money API is certainly not aimed at you, nor at your business colleagues. What if one of that API's purposes is to support monetary transactions on gaming platforms? Then game developers might reasonably be your primary human audience, right? and game developers don't know much about the way your bank thinks and deals with money, right?

As for any service touchpoint, don't design an API around your business, but around the needs and understandings of those who will consume it.

A few design methods that can really help you designing great API experiences

  1. interview target developers : what do they expect from the API and what do they understand about the business behind it,
  2. build personas out of the insights from these interviews,
  3. benchmark other APIs and their documentation to see what conventions are at play there,
  4. prototype and user test the API before the single line of API logic. Provide the developers with a static mockup of the API response and do a walkthrough with them.

Further readings

The user experience of an API is a relatively new concern, yet – and as usual with new things – several people and organisations are developing it:


Tell us what you think