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

Default Yes vs. Default No

Are you and your team members default yes, or default no? One is good for startups, the other not so much.

Check Your Echo Chamber

The people you surround yourself with create your reality. Choose carefully.

Don't Forget the Goal

There's only one thing that matters when you're building software.

How To Get a Job Offer

Want to get a job in the field you love easily? This is how.

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