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

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.

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.

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.

Sharing is the Currency of the Web

You consume free content all day on the web. The best way to pay back the people creating it? Share it.

The Magic of Low Fidelity

High-fidelity documentation is great, but it has a hidden dark side. Learn to embrace low-fidelity documentation, and you'll be amazed at the benefits.

Why You Should Blog More (Data)

When you stop blogging, people stop coming. Simple enough. Here's the proof.

Using a Linter Will Make You a Better Dev

Using a linter while you write code won't only make your code better formatted, it'll make you a better programmer.

Everyone Is Self Employed

The idea that you're not self-employed if you work fulltime somewhere is wrong. EVERYONE is self-employed.

The Real Reason to Learn to Code

Not everyone needs to be a programmer, but learning a little bit of coding can help in a lot of different areas.