An API is a User Interface

For the past few months, I’ve been working on an API project, helping design the architecture of the API, document that, and help with some of the implementation of it. You might ask why me, a UX guy, is screwing around with API design.

Because an API is a user interface, that’s why.

On said project, I was recently discussing some naming conventions with another colleague on the project. He’d made the comment that the naming didn’t matter, that it was a “machine interface”. The problem is, it’s not. APIs are consumed first by humans as they develop against them, then by machines.

This is important, because approaching APIs like they’re user interfaces means we have to design them with the same care and thought that we design the front-end of a product. We have to ensure that it follows standard conventions, that the naming is easy to understand, and that it’s as self-explanatory as possible for a developer consuming it.

For the past few months, I’ve been using Swagger to document this API, and I’m super excited about it. Besides providing a set of tool automation around the API (auto-generating mock APIs, tests, etc.), it provides a fixed taxonomy for describing the API, which helps drive consistency that makes it much easier to consume as a developer. If you haven’t checked it out, I definitely recommend you do.

Bottom line is this: APIs are consumed by people. Yes, machines use them day-to-day, but they have to be easy to understand by the folks writing the code to make the machines use them. Besides, if you’re looking to get others integrating with your API, the ease of use will be a big factor in that adoption rate.

Don’t think of APIs as a low-level machine interface. Elevate them to the same first-class status as your primary UI of your product, and treat them as what they are: a user interface.

Related Posts

Required Reading for All Couples

If you're married, about to get married, or just committed to someone for a long period of time, these three books are absolutely required reading.

I Launched a New Podcast, and I Want You to Call In

I just launched a new podcast called Design By Committee, dedicated to answering your questions about UX, product design, content, strategy and anything else tech.

Shitty Sales Have Made Product Development Harder

Shitty, one-sided sales processes have made product development much more difficult for early stage startups.

Why I'm Cold Emailing You

You might have gotten a cold email from me. Tasteless? Some people think so. Here's why I'm doing it.

How I Found Your Email

I've been cold emailing a lot of people, and many folks are surprised that I found their email. Here's where I dug it up.

Sales is User Research, Undercover

Announcement: The Most Exciting Thing I've Done

Today, I'm announcing the most exciting project I've been involved with. It's called CrowdSync, and it helps to automate paperwork, communication and logistics when dealing with groups of people. Read on for why this is so big.

Three Ways to Start Talking to Users

How to Post to Private Slack Channels from Zapier

If you automate posting to Slack via Zapier, you might need to post to a private channel. It's not entirely obvious how to do it, but actually pretty damn easy.

A Peek Inside our UX Process