Documentation Best Practices for Web APIs

Programmable Web has a nice article called Web API Documentation Best Practices. It brings up several important points about how API developers should document their APIs. Consider this article a call to API developers — maintain your documentation!

According to the article, API developers should

  • Auto-generate Documentation
  • Include Sample Code
  • Show Example Requests and Responses
  • Explain Authentication and Error Handling

They also provide an example site that follows these guidelines. I'd like to add some more best practices, and also discuss a few sites who don't play nice.

1. Readability

blurry

One of the most important aspects of documentation is readability. If your documentation (visually) is difficult to follow, I won't be able to understand or implement it. The FlightCaster developer docs are an example of this. They've done a great job cleaning up the documentation (see my FlightCaster article), but there are no tables or lines delimiting each section, and links are duplicated on other pages. It took hours to sort out what methods I had already implemented when going through it.

2. Accuracy

crosshairs

This is by far the most important attribute your documentation can have — it must be exhaustive, and it MUST reflect the way the API currently works.

The worst examples of API documentation I've found so far are:

  1. World Bank

  2. The documentation is organized and includes sample method calls, but has a few drawbacks:

    • Uses two different API endpoint URLs (api.worldbank.org and open.worldbank.org) at different times
    • Inaccurate URLs (some methods indicate an API key, while the documentation says no key is required)
    • Inconsistent results format

    Let me explain that last one. The Country Query page describes the return results from a Countries query:

    • 3 letter ISO 3166-1 alpha-3 code code
    • 2 letter ISO 3166-1 alpha-2 code code
    • Name
    • Region id
    • Region Name
    • Income Level
    • Lending Type
    • Capital City
    • Longitude
    • Latitude

    That's ten data points, but if you look at the example query, there are only eight nodes:

    <wb:countries page="1" pages="1" per_page="50" total="1">
      <wb:country id="BRA">
        <wb:iso2Code>BR</wb:iso2Code>
        <wb:name>Brazil</wb:name>
        <wb:region id="LCR">Latin America & Caribbean</wb:region>
        <wb:incomeLevel id="UMC">Upper middle income</wb:incomeLevel>
        <wb:lendingType id="IBD">IBRD only</wb:lendingType>
        <wb:capitalCity>Brasilia</wb:capitalCity>
        <wb:longitude>-47.9291687</wb:longitude>
        <wb:latitude>-15.7801476</wb:latitude>
      </wb:country>
    </wb:countries>

    If you look carefully, the 3 letter ISO 3166-1 alpha-3 code code (BRA) is actually an attribute of the country tag, not a tag in itself. Same for the Region ID (LCR). This means that to extract the information that the documentation says the API returns, you need to do a traditional loop plus additional parsing. You'll see the awkwardness when I finally post my World Bank API VBA sample code.

    Also, and I realize this is nitpicking, but who writes tags like that? It looks more like a WSDL document than XML. While technically correct, it's an odd implementation.

  3. OAuth

  4. The self-described Authoritative Guide to OAuth 1.0 has very little instructions on how to actually implement it on any given platform. It's more of an "About" page than a "How To" page. The history of OAuth doesn't belong in a guide explaining how to use it; put it in a FAQ or somewhere else on the site for those that care. The "Beginner's" guide actually contains more sample code than the "Authoritative" Guide, but most of the Beginner's guide is lost in a wordy, generic explanation of how OAuth operates (and I do mean wordy). You have to read through the Core (whatever that means) if you want any hope of understanding how to implement it.

    I still do plan on posting detailed walkthroughs for using OAuth with VB(A) for services like Twitter. But they aren't making it easy to learn how!

    Both guides are in love with their own terminology and makes wild assumptions about the technical expertise of their readers. For example, the Beginner's guide instructions for signing requests starts off with the following:

    In the following walkthrough, the Consumer would like to access a Protect Resource located at http://photos.example.net/photos with the parameters size=original, file=vacation.jpg

    Simple enough, right? Even if you don't know what "Consumer" means. But immediately following, it continues as follows:

    The Consumer has previously registered with the Service Provider and obtained the Consumer Key dpf43f3p2l4k3l03 and Consumer Secret kd94hf93k423kf44. It has executed the OAuth workflow and obtained a Token nnch734d00sl2jdk and Token Secret pfkkdhi9sl3r4s00. To sign the request, the Consumer is using the HMAC-SHA1 signature method and generated a nonce string kllo9940pd9333jh and timestamp 1191242096.

    Huh? How do I register and how do I get a consumer key? What is the "OAuth workflow" and how to I obtain a token and token secret? How do I use the HMAC-SHA1 signature method with OAuth? How do I generate a nonce string, what is the syntax and how long does it have to be? Why does the timestamp look like that? These are major assumptions that are casually glossed over by the guide. Nowhere in the guide (or anywhere else I looked on the site) are there links to any other resources, nor are there any links to service providers like Twitter or Google that use OAuth. I would be (extremely) grateful to hear otherwise.

    The comments on the guides left by visitors are a mix of fanboy-praise and people who can't implement their code.

So my search for OAuth sample code, or some kind of walkthrough, will continue. I may just be bitter because Twitter requires OAuth now, and my userforms all broke, but as I mentioned earlier, I think using OAuth to protect something as silly as tweets is excessive. A tweet and $2.25 will get you on the subway.

Here are some great APIs I've had the pleasure of writing code for.

Business.Gov

This API is well documented with method calls and sample URLs. It lists return data formats as well as the format for individual return values. It is consistent and cleanly formatted. The first of a large volume of sample VBA code for this API may be found at Business.gov Web API – Financing.

Abbreviations

The documentation for this API is beautifully simple, yet complete. Sample XML responses are even included, so you don't even need to run test queries. VBA code for this API may be found at Abbreviations.com API Code Samples.

Any other APIs you'd like to mention, for better or worse?

About JP

I'm just an average guy who writes VBA code for a living. This is my personal blog. Excel and Outlook are my thing, with a sprinkle of Access and Word here and there. Follow this space to learn more about VBA. Keep Reading »


Related Articles:


Share This Article:

Share and bookmark this articledelicious buttonfacebook buttonlinkedin buttonstumbleupon buttontwitter button

comment bubble 2 Comment(s) on Documentation Best Practices for Web APIs:

  1. Thanks for talking about my article. In that posting, I tried to focus on issues that affected Web APIs (as opposed to all APIs), but if you want to read my ideas on API documentation in general (how to create good sample code, how to come up with good use cases, how to write docs if you are a coder, etc.), you can find other articles I've written at http://sdkbridge.com/work.php.

    You have excellent thoughts in this post. I'm glad to hear that I'm not the only one who has been mystified by trying to figure out OAuth.

    • Thanks for sharing, Peter. Instead of oAuth, as developers we can always ask Twitter for permission to use xAuth. And for desktop applications (Excel being one), they offer Out-of-band/PIN code authentication which is slightly less complicated.

This article is closed to any future comments.
Excel School