The UX of APIs

This December 1st, Helen kicked off our Christmas calendar with a bit of a rant, concerning titles.

I couldn’t agree more.

And this year, I came across a challenge that really put this in perspective for me:

The APIs we were delivering, weren’t doing their job.

Well, that’s not exactly true. We were making APIs that worked – others could use them to build their own digital solutions. But it was difficult for them to figure out just how they could make use of them, and develop stuff with them.

And it occurred to me then, as I started looking into that problem, that APIs are as much of a service as running an airport express train and needs just as much design attention if they’re to be great services. And it’s not just about touchpoint-design – like the documentation website – but the design of the APIs in themselves, the communication channels surrounding them, the onboarding process of new developers, security and access levels.

I hadn’t really given APIs much thought as a designer before, I must confess.

I am an interaction design, with 12 years of experience. And my UX playground has certainly grown over the years; from doing strictly user interface interaction specifications and information structures way back in 2007, I now deal with the attractiveness of our digital products, with how our cross-functional teams deliver and collaborate, the viability of our ideas, the organizational intricacies of setting clear goals for digital services and how we work to reach them, the completeness of the customer journey our products are part of and underpin – along with the usability and desirability and doability of it all.

And yet – paying attention to our APIs as a designer and product developer hadn’t really occurred to me as part of responsibility.

I thought of APIs – like most of the organization around me did – as the developers’ responsibility. Alone. It was their delivery – not mine. I don’t handle code. I’m a designer.

Big mistake!

Because fairly soon, we experienced exactly what you would expect when you don’t pay attention to the user experience of your product or service: our users found our APIs difficult to use. And delightfulness? Forget about it. We were – as I believe many are – focused on delivering functional APIs. As long as they worked, we’d met the requirements. I mean – delightful APIs? Come on.

But it is a thing, as I came to learn. Once I started interviewing developers – as good old fashioned user insight – I found different sets of needs, of motivational factors, barriers – and examples and stories of how APIs can delight them, frustrate them, confuse them, and make them want to build more with them.

And it opened up a whole new way of thinking – both for me as a designer, but also for our organization.

And seeing that it is already December 11th, and Christmas is almost around the corner, and that we all have a lot of stuff to do, I’d like to end this article with a few concrete examples of how our new mindset manifested itself. I hope what I have written so far, in a small way, might inspire you a bit, to broaden your perspective as a designer – and that the few points that follow might help you improve your organization’s APIs if that is part of your company’s offering.

• We recognized that our API’s are products and the provision of them to others is a service. So we organized ourselves accordingly: set up a cross functional product team with
  • a product owner to manage the development of the APIs as service - across all the API-delivering teams
  • a UX designer to bring the user’s perspective into the process (and design touchpoints)
  • two developers to assess the design of the APIs in themselves and develop the touchpoints needed for communication with our users

1. We set up ambitions for our APIs like we had on our other digital services and products. I have included them at the bottom of the article. We set them up specifically for our work with our APIs, but they’re quite general, and even if they reflect our specific challenges with our APIs, I believe they will resonate with many API-providers out there.
2. Just like we set up ambitions, we also decided on a few metrics to watch, to see that we were succeeding with our work.
3. We started doing user interviews with developers whom were using our APIs. This was a tough one – it felt like being a completely fresh off the farm UX designer again. It’s been a long time since I have been so unsure and unfamiliar with the subject matter at hand. Understanding developers talking about how they experienced our APIs? Hello, darkness, my old friend. Half of the time I just wrote down the sounds I heard, trusting I could ask a developer colleague later what it meant, and reminding myself that it’s not really what they’ve done but how they experienced it that matters right now. It was rough – but felt kind of good, too. I couldn’t rely so much on my own experience and assumptions anymore, and that felt…well, healthy.
4. We did other insight activities as well, just like we would for any other service or product we’d design and develop.
5. We drew up a service framework for our APIs, with the different stages of the customer journey (onboarding being our prioritized stage), different user segments (professional developers in bigger organizations – in different sectors and markets, individual developers – we have a few open APIs, students, etc.) with different needs and offers, and: most important touchpoints. The APIs in themselves being number one, of course, then change logs/change notifications, our documentation website and direct communication channels.

The key take-away for me, from the user interviews, was how important a user centric view was even when developing APIs. We had developed APIs based on functional specs – API this shall make that possible. And when it was possible – we were done. But when we interviewed the developers using our APIs it became clear that what would have been helpful for them, would have been developing our APIs based on what they would most likely want to build on top of them. Separating the different APIs after feature areas relevant for our prioritized users, designing objects in a way that most likely would answer to their specific need.

In the end, designing the actual API and develop them falls on the developers: I am simply too far removed from API as a material to efficiently and effectively design for it. But what I was able to do, once I had taken off my tunnel vision goggles, and look outside my regular design box, was to make that part of our delivery, which up until now had not been recognized as a service or product, and put it in a user centric perspective – and thereby adding value to that delivery as well.

(I have, however, included a few links to articles on designing APIs that I found very useful in understanding what good UX for APIs is or can be all about. If you're curious and fancy broaden your designer horizon a bit, check them out)

To quote Helen again:

And for us, that would have meant that we probably would have caught on a lot faster on the importance of designing APIs as a real service. If I had been more curious about that part of the developers’ job, and they had been more curious about my bringings to the table – I think we could have saved us and our users a whole lot of trouble and delivered a more powerful service sooner.

UX is everywhere – and you can live long and prosper a lot more if you take a look around and not let titles and old assumptions bog you down.