Can APX help in developing usable and accessible APIs?

APIs may have been around in some form or another for decades, but in recent years they have evolved into business channels that extend the reach of an application beyond the visible user interface. We are moving from a "direct" model where features are exposed through a single UI to an "indirect" model where they are exposed via a third party using an API.

Although APIs open up a range of possibilities that extend the reach of a system, they tend to defined by unnecessary complexity. A “good” API should be accessible, easy to understand and quick to engage with. Few of them meet these basic criteria.

How can UX apply to APIs?

The direct relationship between usability and value is widely understood for user interfaces. Design investment is easy to justify as a well-judged change to an e-commerce site can generate a significant and measurable uplift in revenue. An entire professional discipline – UX - has grown up around perfecting this optimisation of interface design within the wider context of the user experience. Is there an equivalent discipline for API design – APX?

UX takes into account every aspect of the customer’s experience of a product or service. It requires that you develop a detailed understanding of the circumstances and motives that shape a customer’s perception. Techniques such as personas and scenarios are used to identify key interactions. Prototypes are developed iteratively and validated by user testing long before any code is written.

On the face of it, APIs are customer interfaces and should benefit from the same customer-driven approach to understanding the design. However, many UX professionals come from design backgrounds so have difficulty getting to grips with the technical concepts underpinning of API design.  By the same token, technology specialists are too steeped in implementation detail to be able to get under the skin of integrators and understand how their API designs are perceived.

Starting with the basics

On a very basic level a better understanding of how the API will be used should drive key design decisions, e.g.

  • Is it a single-purpose service or a more generic provider to support orchestration?
  • Will it serve back-end processes or front-end applications?
  • Will it be accessed by mobile devices with limited bandwidth?
  • What volume and peaks of data should be expected?

These kinds of decisions have a real impact on your API design. A mobile application will have limited bandwidth so will benefit from simple methods based on REST with very small response payloads. Larger-scale integrations may involve more complex exchanges that suit a more structured API based on SOAP. If an API has to support high data volumes or numerous similar requests then it may need to have a caching strategy built into it.

Beyond these technology-driven basics an API should focus on what’s important to the user. Developers tend to worry about how to implement and publish an API while users are more concerned about how to discover and explore it.

An API is like a little language so it’s important to remain both consistent and easy to understand. With this in mind, you shouldn’t expose your dirty laundry to the general public by surfacing your internal implementation detail. It will only serve to inhibit your scope for changing the implementation in the future.

It’s also easy to fall into the trap of assuming that the internal language used in your organisation is the most sensible way of describing a problem domain. This allows implementation leaks into API definitions and it is more likely to appear as arcane jargon to external users.

You can’t use A\B testing on an API…

Once published, an API is forever.

Changing an API design often means that you are forcing any connected application to update their integration. This gives your customers an excuse to change supplier, which they will be more inclined to do if you force development work on them.

This commercial restraint highlights a key difference between UX and APX. An API is often immutable and you cannot change it as freely as a user interface. Marketing teams will use techniques such as A\B and multivariate testing to evolve their interfaces in response to real-time customer behaviour. APIs are not afforded the same luxury. Once a customer integrates with an API you are bound by a contract to maintain its current shape. You can get away with additive changes that don’t break backwards compatibility, but your freedom to re-shape your design is very limited indeed.

…but you can prototype it

Given how long you are going to have to live with your API design decisions it makes sense to invest in developing an up-front understanding of the use cases. You should also be validating these use cases by building multiple integrations against the design.

Will Tracz described the “rule of three” where a component has to be tried out in at least three different contexts before it can be accepted as re-usable. A similar principal should be applied to API design. If you can prove your API design against three different contexts then it’s likely to hold up against the various use cases that you haven’t even thought of yet,

UX and APX are not the same

At first glance, UX may appear to be directly applicable to API design. The up-front work required to understand the user is absolutely necessary and any design should be validated before it is put into production. Too many times I have seen developers dive straight into an implementation and the end result is usually an API design that is driven by the internal implementation details.

However, once an API has been published there is an immediate loss of design flexibility that is not usually felt by a user interface. APX has to take into account a wider range of influences than just the customer’s immediate needs. It has to be designed with future expansion in mind, but not so much that it becomes meaningless today. Concerns over future scale and demand management can over-rule ease of use if it ensured uninterrupted service. This contributes to an approach that should be more customer-centric, just not overwhelmingly so.