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:

Lob.com 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

Default Yes vs. Default No

Are you and your team members default yes, or default no? One is good for startups, the other not so much.

Check Your Echo Chamber

The people you surround yourself with create your reality. Choose carefully.

Don't Forget the Goal

There's only one thing that matters when you're building software.

How To Get a Job Offer

Want to get a job in the field you love easily? This is how.

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