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

Review: Keto Diet

I recently gave the Keto (Ketogenic) Diet a try. Suffice to works.

You Don't Need to Get it All Correct Immediately

Too many people wait on shit to be perfect. Get it close, leave out some stuff, and set yourself up to quickly iterate.

Using Foundation 6 in Angular 4 (or 2)

How to use Foundation for Sites 6 in Angular 4 (or any version 2+)

Great Products Need Great DevOps

In the quest for shipping great products, DevOps is often overlooked, and that's a mistake

How I Increased my Water Intake by 500%

We all need to drink more water, but it's hard to get in the habit. Here's a simple trick I used to get a 5x improvement on my intake.

Three Secrets That Made Cutting The Cord Easy

After decades of being attached at the hip to cable, I finally cut the cord, and it's been amazing. Here are three secrets that helped me get the most of it.

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.