The extremely boring thing that will make or break your API business

One of the pages on our website gets 150% more traffic than any other page.
 
It’s not the “About.” It’s not our pricing page. Not even this blog. It’s arguably the least interesting thing on the site:

It’s our Documentation page. It’s not inherently eye-catching, but it has all the necessary tools for developers to succeed with the API: getting started guides, high-level explanations of what the API does, a thorough description of endpoints and fields, and any limitations.

But the fact that this boring page gets all the attention is great for us — it means that our docs are actually useful. 
 
If you’re trying to monetize your API, you can’t get away with just throwing together a list of params and calling it a day. Currently, there are about 50,000 web APIs out there, most of which are free and most of which are painful to work with — either due to poor design or poor maintenance. Developers have become wary about which APIs to adopt. 
 
Your documentation is the only way to prove that you have a product that actually makes developers’ lives easier — it’s your one chance to rise above the noise. 
 
Great docs need to address the needs of developers at three different stages:

• Perusing developers, who are trying to figure out if your API is appropriate for their use-case.
• Interested developers, who think your tool is appropriate, but need to try it out before deciding they want to invest.
• Invested developers, who have implemented your API and need to debug or make adjustments to how they’re using it.

Failing to address any one of these will discourage developers from using your API. If you don’t take the time to help developers through the process of learning about and implementing your API, they’re not going to spend time and money to get to know your product. The API you’ve created is meant to be part of an ecosystem, so you need to create the tools and resources for it to become embedded in that ecosystem.
 
Here is how to create great documentation for every stage of investment in your API product.

Show Usefulness for the Perusing Developer

A perusing developer is looking for proof that your API provides the functionality that they need. Before throwing them knee-deep into resources and endpoints, explain what your API does, and show how it works in the real world. 
 
This starts with a high-level explanation and human-friendly descriptions throughout your documentation. On ipinfo.io, the first thing you read is precisely why you would want to use the API, and where it saves you trouble. This is essentially our value prop:

Slack’s suite of APIs can be used in several different ways, all of which are described on the home page:

A developer who is interested in, say, adding messaging functionality to their app, can see that one of Slack’s APIs helps with precisely that. They don’t have to skim through pages of documentation or read through long discussions on Stack Overflow to get a vague understanding of what the API can be used for.
 
Once you’ve piqued the curiosity of the perusing developer, you need to show them how it works with plenty of code examples. This helps bridge the unfamiliar — the new calls and methods the developer is looking at — with the familiar — the code they’re used to working with. It helps them see a concrete application of the abstract feature that they’re being promised.

IPinfo is a singular API with a pretty straightforward application — get geolocation data. If you have a suite of APIs or an API that has more potential use-cases, you’ll need more code examples to show what your product is capable of. 
 
One of the best ways to do this without cluttering your page is to show code examples in a panel parallel to the documentation:

If you’re selling an API as a product, your objective should be to make a good first impression on the perusing developer. But leaving developers with just a bunch of endpoints and methods creates friction because developers have to figure out the logic and nomenclature that you created for the specific purpose of this product. 
 
Clear description paired with plenty of example code, however, communicates the value of your API in a language that the developer is already familiar with.

Make The API Accessible to the Interested Developer

Once a developer has become interested in your API based on your descriptions, resources, and sample code, they’re going to be eager to start tinkering. At this point, it’s imperative that you make it as easy as possible for them to try out your product with guides and helper libraries.
 
IPinfo’s “Get Started” guide lets developers get a sense of how the API works in seconds — without any sign up or authentication necessary. We simply provide a curl command that the developer can just drop into their command line, and get a response:

For those who want to go deeper, we created several guides to run developers through all the popular use-cases for the API:

We created these guides based on what we learned from our users. 
 
For instance, our guide to replacing “getCurrentPosition()” was made in response to a trend that we saw online. We were seeing questions popping up about depreciated features with Google’s geolocation API:

For every question that’s raised on StackOverflow, there are dozens of developers dealing with that same problem. As soon as we saw an opportunity to add another guide through a popular use case, we added it to our page, so that we could show off more of what the API is capable of.

An additional way to help developers get started is to provide client or helper libraries. They’re the best way to hand over your API to developers in a format that is already useful to them. 
 
You can choose to build out help libraries yourself, but often, your customers can do a lot of the work for you. Our “client libraries” page links out to third-party wrappers and libraries that were put together by people who actually use our services.

Linking out to the work of fellow developers helps us establish good will in the developer community, and gives us an understanding of who our customers are. Devs using our product aren’t just customers, they’re fellow engineers that help us build IPinfo just as much as IPinfo helps them build their software.

Enable Troubleshooting for the Invested Developer

There’s only so many oh, sh** moments that your customers will stand before switching to a different API or building out the feature themselves. To catch these moments, you need to make sure that you give the developers everything they need to troubleshoot the API if that something goes wrong. This means giving your customers an understanding of what went wrong in context, and then making your docs highly navigable for when they look up error handling.
 
Start by providing human-readable HTTP status codes, so that developers have a starting point for diagnosing the issue:

IPinfo returns a short message explaining why a call couldn’t be made. This message is consistent with the one that appears in the documentation as well:

And, for the final touch, this error message is bookmarkable:

All IPinfo documentation is on a single scroll page. There’s a navbar on the left that lets you jump to the part of the documentation that’s most relevant to what you’re trying to accomplish. But jumping also adjusts the URL so they can bookmark and easily reference it later (or send along to a fellow developer).
 
Your documentation will rarely be read top to bottom — –it will be skimmed, scrolled, and navigated via CTRL-F. So while it’s important for your documentation to be thorough, it’s even more important for those docs to be navigable. Keeping everything on a single, easy-to-navigate page will help developers find the information they need, when and where they need it.

The Devil is in the Details

Developers rarely give the same attention to their documentation as they do to their code. They consider their code to be their craft, and the documentation to be an annoying schlep afterward. This leads to great APIs that no one will ever use.
 
Your documentation is the bridge to your API — it makes something you’ve invented accessible to tens of thousands of developers in a language and format they can understand. If you can put as much detail and thought into your documentation as you do to your code, you can multiply the number of developers that will be excited to use it.

IPinfo is a comprehensive IP data and API provider with flexible pricing plans to meet your business needs. We handle billions of API requests per month, serving data like IP geolocation, ASN, mobile carrier, and hosted domains. Sign up for a free account or contact our sales team to learn more.