Examples of Awesome API Documentation

In the process of building an API?  Looking to get started on your first API integration project?  Below is a list of some of my favorite API documentation sites.

PubNub

Maintains one of the best examples of how to have a very complex system under the hood, while keeping a cool and organized API outline.  Oh, and the dev console is plain cool.

PubNub JavaScript SDK | JavaScript SDK 2013-11-06 22-39-07

Console 2013-11-06 22-40-53

Mandrill

Example JSON requests on each method page makes it easy for a developer to see the exact format their application should be communicating with the API.

mandrill

Stripe

Simple and logical method names like cards, customers, and coupons allow Stripe to build a dead-simple structure to house a robust API.

stripe

Context.io

Extremely well-organized, color coded, and built-in real test examples on each resource page.

Context.IO | The missing email API to leverage email data 2013-11-06 22-56-08

Searchify

Less is more.  Searchify keeps their documentation lean, and makes it very easy to understand.

searchify

Plivo

Inviting documentation that is easy on the eyes.  Fonts and other text emphasis makes it easy to hop around the documentation and find what you are looking for.

plivo

Have an example to add to the list?  Leave it in the comments.

Tools to generate beautiful web API documentation

Edit 6/16/2013: It’s been a few months, and we finally ended up going with the Swagger-based documentation built into 3Scale.net.  Want to see how it looks?  Head over to developer.nutritionix.com.

— Begin original post —

As demand for our Nutritionix API is starting to grow rapidly, we have been working on finding an API documentation engine to meet our needs for the long-term.  I was not able to find any comprehensive list of existing API documentation solutions, so I am compiling what I have found so far. Please leave feedback on your own experience in the comments.

Web API Documentation Tools

We are still exploring each solution, but I will update this post as we learn more about each option.

  • Swagger – A specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. [Demo]
    • Note: We already use 3Scale.net for our API management solution, and they have an ActiveDocs feature based on Swagger.
  • I/O Docs – By defining APIs at the resource, method and parameter levels in a JSON schema, I/O Docs will generate a JavaScript client interface [Demo].  I/O docs was created by the API management platform Mashery.
  • apiary.io – Provides very quick way to get your documentation up and running, includes GitHub integration and I/O validation. – Suggested by Siyfion via Reddit.
  • Docco – Docco is a quick-and-dirty, hundred-line-long, literate-programming-style documentation generator. It produces HTML that displays your comments alongside your code.
  • Dexy – Flexible documentation tool that supports any language, for any API.
  • Doxygen – Generate an on-line documentation browser (in HTML) and/or an off-line reference manual, and you can configure doxygen to extract the code structure from undocumented source files.  Seems more technical than the other options, but a powerful option nonetheless.  Suggested by gkumar007 via Reddit.
  • TurnAPI – Paid service.  Intelligent WIKI-editor, markdown based standards, documentation branching, sync with Git, SVN, Mercurial, clean looking themes. [Features]
    • Note: As of writing I was unable to create an account at TurnAPI.

Edit 6/16/2013: It’s been a few months, and we finally ended up going with the Swagger-based documentation built into 3Scale.net.  Want to see how it looks?  Head over to developer.nutritionix.com