How to write API documentation

Writing documentation for an API may seem completely daunting if you've never done it before. Many product managers do manage APIs - either exclusively or as part of their suite of product and features, must know how to do this.

When you find yourself managing an API, chances are you'll be tasked with updating existing documentation, or writing new documentation from scratch. This may feel overwhelming. Don't panic! I'll give you a starting point and some tips in this post.

Follow these 7 steps to get started. 

API_Documentation.jpeg

This isn't a comprehensive guide as API documentation needs vary wildly, but this will at least give you a starting point, and on the right track to comprehensive documentation for your API.

1. Explain what the API is and does

The description doesn't have to sound extremely technical. Here's a one line description Facebook uses to introduce its Graph API:

  • "The primary way for apps to read and write to the Facebook social graph."

That's simple. Make this description relatable for both technical and non-technical users.

 

 

2. Spell out the 'properties' and corresponding descriptions

The terminology for what you're describing will vary slightly depending on your API. For my API, I describe the 'fields' of the JSON response.

Here's an example for one of Amazon's public APIs - it describes 'properties.'

Going back to our Facebook Graph API, it describes 'nodes.' Ask your dev team what is appropriate to call out, and what the correct terminology is for your product.

 

 

3. Show example GET requests and responses.

This is perhaps the most important component of good API documentation, and most developers (users of your documentation) will skim the doc until they find this section specifically. Most often, devs just want to want to see examples of GET requests. 

Screen Shot 2017-10-05 at 7.57.18 AM.png

Here in an example of Instagram's Public API, they show the GET request alongside the accompanying response.

It also has a simple description of the call and response - "Get a list of recent comments on a media object." Easy.

Also, this example involves Snoop Dogg which is amazing.

I really like this format as it's clean, clear, and simple. 

 

 

4. Call out exceptions, offer workarounds

Call out any tricky edge cases or exceptions to the rule. This will save you time as users of your API will inevitably reach out to you with questions about these exceptions.

Here's an example from CNN's Search API documentation. They've included a section for 'General Usage Notes'  where they call out the exception and then provide a workaround.

Screen Shot 2017-10-05 at 7.45.38 AM.png

 

 

5. Compile an FAQ

If you own an API as part of your product, questions about how to use that API may come directly to you, the product manager. (This is the case in my current product role).

Document these questions, keep a running list, and add them to an FAQ section of your API documentation. Instead of answering each of these questions as they come in, point your users to the FAQ.

Also, by compiling this FAQ, it keeps you on your toes about what issues users of your API are having, which can help you with your ongoing effort to improve your API.

 

 

6. Spell out a complete use case

This is super helpful to point other product managers so they can visualize what your API can do. It doesn't need to be complex. 

Here's an example from AccuWeather's API documentation

Screen Shot 2017-10-05 at 4.08.25 PM.png

 

 

7. Consult your engineering teams!

Please, dear god, please, get feedback from your technical folks who actually build this damn API.

Trust me, they will be already be extremely pleased that you're helping with the tedious task of API documentation. Ask them questions, show them drafts of the documentation, take feedback, iterate.

You may have to do this a few times before the documentation is solid. Don't worry about sounding idiotic. The more questions you ask, the less clueless you'll sound in the end.

These 7 steps are not comprehensive,  but can serve as a starting point. 

You may also have to include: 

  1. Steps for how to set up a developer's environment
  2. Using a specific Library
  3. Specifics around Permissions
  4. Anything else that is relevant to your specific API

Here are some example API docs to help you see how they're organized. 

 

Amazon's Developer Publishing API

Google Maps API Home

Uber's Public API Documentation

Yahoo Weather's Public API

 

Although API documentation is a tedious task, it is a very important part of your API's user experience.

If your documentation sucks, developers trying to use your API will get frustrated. So go get started on your awesome API documentation!