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

Review: Keto Diet

I recently gave the Keto (Ketogenic) Diet a try. Suffice to say...it 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.