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

How to Onboard a Product Designer

If you're bringing a product designer or UX designer in to help you design your product, there's a bad way to do it, and a good way to do it. Here's how to make sure you're doing it right.

Review: Slicing Pie

Slicing Pie is a new way to think about company equity splits, and it blows away the old methods you've probably used.

When Troubleshooting, Follow the Process!

When you're trying to troubleshoot something - a car that won't start, or a business that isn't working - follow the right process.

The Art of Finding a Way

Being resourceful and relentless is one of the keys to being successful (and a great shipper). When in doubt, find a way.

Why I Have a Cocktail at 3:30 Every Day

Every day at 3:30, I stop what I'm doing and have a cocktail. It's become an incredibly important part of my daily routine.

Everyone In a Startup Should Have This Skill

You know you need technical skills to build the product, and sales skills to sell it, but does your team have this critical skill?

Doing Things Makes You Feel Better

If you're feeling down, depressed or just in a blah mood, do something. Anything. Make a thing, clean a room. Action makes you feel better.

Review: Auth0

Auth0 is a service that provides identity as a service, so you never have to build authentication again. Here, I lay out the good and the bad.

Why I Unfollowed Everyone on Twitter

I unfollowed everyone (~4,500 people) on Twitter. Here's why I'd do such an insane thing.

How to Turn Off Facebook Live Notifications

Facebook Live is cool, but the constant notifications about new videos aren't. Here's how to turn them off and get some peace.