UX Design and APIs

What is the role of UX Design in API design?

Lots of designers find this difficult - as a lot of them came from a visual or industrial design background, it can be hard to engage with user interfaces that manifest non-visually, like data or APIs.

In addition, developers often don't help engage designers on this topic - they think this is a developer realm, not a user experience realm. And as developers, they understand what other developers need, right?

However.... as the famous adage says... You Are Not The User. Even if you might do some or all of the same job as the user. Even if you’re building an interface for someone with your exact job title, you don’t have their constraints, tools, or context. So you're still not the user. This counts equally for APIs instead of a colourful web interface.

APIs in the context of a large sociotechnical system

An earlier experience put me responsible for about 150 interfaces into different customer invoicing and billing systems. At one side, social workers, flexible with nuance and often heavy on the jargon (at least on the paperwork). At the other side, accounts receivable, accounts payable, aged debt. A mistake in how this overall process is designed and used could make the difference between someone getting a large print invoice (if needed) with easy to scan explanations of what they are paying for vs a difficult to read list of items filled with jargon.

These specifications would come in via an IT team at the customer typically, who had no exposure to either sides of that exchange of data. So they'd sit saying things like "ah yes 128 characters is fine to explain what the invoice item is, people don't like to read lots".

The inevitable result was outputs that made lots of sense to IT, management, even the project team, but no sense in the real world. It took a good couple of years to even identify the problem because the destination systems were producing paperwork and actions not viewable by anyone who had been involved in designing the API or interface, or were supporting it later.

How UX Design can help

This is the expertise the designer can help a team with. They can make sense of the sets of people involved and distill what matters:

• The person who writes code to interact with the API
• The person who uses the system that the API is interacting with, and vice versa
• The config and data in the source system, and the people that is trying to accommodate
• The customers or people who are using the outputs from the destination system

Ok, so the next question is - how does this knowledge affect the API and interface designed? ie, how can the developer use it:

• Data Model design - names of fields, field lengths, formats can be adjusted based on knowledge shared
• Ontology design in the Data Model, eg Is there a 1:1 mapping between an invoice and a credit note? Is the 1:1 relationship on the invoice itself or the invoice item?
• Scalability and robustness - is this API likely to be called by thousands of other systems in a freeform, ad hoc sort of manner, with lots of requests a second? Or is it mainly used for a batch job done once a day or week? Is it being called via scripts, a more ad hoc tool like Zapier or a full software product?
• Security - is this API being used in a corporate environment with a cybersecurity system that might monitor or control traffic? Is it on the public internet? How sensitive is the data being transferred?
• Test data and prototyping - gaining access to that config in destination systems or even just some context allows more realistic test scenarios, and easier prototyping

In conclusion

• Most designers aren’t trained to think about data models and response codes but maybe it’s time they were.
• If you get a designer game to assist with your API design... you have found a unicorn. don't squander it.
• If you're not lucky enough to have a designer - see if you find out about who is using the API, and what they're using it for, and who they are providing outputs for. You'd be surprised what you might find out.

And if you're curious about how I helped fix the finance interfaces... that's coming in another post.