Write Your API With UX in Mind


Written by


The featured image for this blog post.

You probably write bad APIs.

I’m not saying that to be offensive or inflammatory. I’m saying it because writing good APIs is really hard. Like really, really, ridiculously hard. Take a couple seconds to count the number of APIs you have used that were intuitive and easy to work with. My list fits comfortably on one hand: Stripe, Twilio, and v2 of Sendgrid’s mail API. So you probably don’t write good APIs. If you did, my list would be a whole lot bigger.  


Really, Really, Ridiculously Hard.                                

Not that I’m any better myself. I’ve written my fair share of bad APIs. Hell, a few of them would probably make you wish you had a punching bag in the office. But I’ve been making a serious effort to improve for a while now. And the thing that has made the most difference in the quality of my APIs is writing them with the user in mind.

Writing anything with a frontend and backend is a lot like dancing. It’s a beautiful, beautiful thing when both partners are in sync. And it’s a painful, horribly awkward thing when they’re not.  When you’re getting started building a new API, it can be tempting to dive right in and start coding. Don’t.

Before you write a single line of code you need to get in sync:  


                           1. Don’t start working until you understand what the end user is trying to do. That means looking at the designs for whatever you’re programming an API for. The whole purpose of the frontend is to drive your app’s UI. By learning the ins and outs of the UI you’ll learn your partner’s half of the dance. At Krit, we always:

2. Keep your actual user in mind. It’s not the guy or gal that visits your website or opens your app. It’s the guy or gal that’s using your API. The difference is subtle, because they’re trying to achieve the same thing. But your partner doesn’t have a nice, intuitive GUI to work with, so you’ll need to do the best you can to teach them your half of the dance. That means:

Doing all of those things doesn’t guarantee that your dance will be beautiful. But it does mean you won’t be stepping on your partner’s feet from the get go, and that is a great way to start. A great way to finish, is to be just as mindful of your partner during the dance.                    


As you program, you need to stay in sync.                                                            



                           1. Keep in mind that you’re really writing two separate things. You’re writing a program that does XYZ, and you’re writing an interface for somebody who wants to do XYZ but doesn’t need to know how you do it. The implication being that you should:

This is one of the trickier parts of this blog post, and it is worth noting that if you want to do it well, there are a whole books on the topic. Eric Evans wrote an excellent book about it, and I highly recommend reading it. More importantly DHH and Martin Fowler highly recommend reading it.

2. If you have to make any changes to spec, run them past your partner. Changes happen, changes will happen on the frontend too. The key to dealing with them is to talk about them and stay in sync.

Making a ballroom dance look elegant and effortless is incredibly difficult. On the rare occasion that you see two people make it happen, it was years in the making. Thousands of dances went into making the performance you saw perfect. Programming is the same way. The only way to get better is to practice. You might not be able to do all of these things the next time you write an API. Maybe you’ve got a tight deadline for another project and you can’t afford to take time out your schedule to participate in the design critiques. Maybe you’re client has a super small budget and you can’t afford to take the time to write, and maintain quality documentation. But if you do as much as you can you’re API will be better for it. And if you keep doing more and more each time, you’ll write a great API someday; I guarantee it.