How to Design Great API Documentation

I’ve integrated with, and also built, a healthy number of APIs in my years. Over the course of integrating with and researching a bunch of APIs, I’ve looked at reams of API documentation. The sad fact is, most of it is terrible. From poorly documented endpoints to a lack of code samples, I’ve spent hours pinging endpoints trying to get a request right because the documentation was so bad.

Today, I stumbled across a really cool service named Lob, which is an API for physical mail. Now, I have a bit of a soft spot for this. A buddy of mine and I have been talking about building this exact same type of service for some time, so when I found Lob, it was a nice surprise.

My infatuation only grew when I looked at their API documentation. Now THIS is how APIs should be documented. Let’s take a look: API documentation

This is beautifully done. Methods are broken up nicely on the lefthand side, by functional description, not by endpoint address. Each endpoint has a clear description of what it does, and a very clear set of arguments listed, with the parameters clearly described for each parameter. Finally, the righthand side of the screen features code snippets for each endpoint, available in multiple languages/formats, showing, clearly, the request and response (and even variations on the request if applicable).

This is how all APIs should be documented. It’s clear, to the point, and perfectly descriptive of how a developer can expect to interact with the service. If you’re documenting an API of your own, take note: this is a master class in how to do it right.

Why This Matters

The fact is, if you’re developing an API, you have users. Your users are other developers, and you owe it to them to deliver just as good an experience as you do to your end users of your product (assuming your product isn’t only an API, where your end users ARE the developers!). Developer Experience is a critically important subset of user experience. If you’re creating an API, service, library or other component that involves developers interacting with it, think about them just as you would any other user. They deserve to be treated as first class citizens of your experience, not simply monkeys with a (subpar) manual.

Related Posts

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

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.

Three Ways to Start Talking to Users

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.

A Peek Inside our UX Process