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

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.