Better API documentation coupled with an explorer

August 16th, 2012 by Etan Zapinsky

One of the goals of Chartbeat is to make really complex information really easy to understand - really fast. We keep this in mind when we build anything from a new feature on a dashboard to our heads up display and now our new API Explorer. Instead of creating static API documentation separate from the API explorer, which is confusing to navigate and takes way too long to jump back and forth, we bundled these two things together. So you have a seamless work flow when working with our API. Now, when you look at the documentation for an endpoint, you don't just see a unpersonalized template response, you can actually play around with your own data. It’s a preview of your data with our API. Awesome, right? Play around with a couple of these to see what I mean: These API explorer updates aren’t just an opportunity to explore the capabilities of our API, it also helps to directly integrate our API into your service. On top of providing the results of your API query, you’ll now see what URL would return those same results. From there, you’ll use the URL we provide to mimic the exact results you see in the response.

Now, let’s talk about collaboration. Instead of sending the actual API URL to show someone the response, we created a special syntax for specifying an endpoint and it's parameters within the hash of the URL of the API explorer page itself. This move allows you to show anyone a quick visualization of the information you plan on using without having to build anything. It’s basically magic. API wizardry. After you find the query you were looking for, just send the URL of the API explorer page to your friend/colleague/collaborator-in-crime, and they will be presented with an API explorer form just like you left it. We explain the response completely, so they won’t be bugging you about what a particular field in the response means. Lastly, we took care of a little housekeeping on the UX front for you: Since we want to make accessing your data as easy as possible, all your current API keys are at the top page, and by selecting one it automatically appears in the form. You can also manage your API keys directly from the explorer page. If you suddenly realize you need a new API key adding one is right there - where you’d expect it to be.

So what do you think? A little more helpful, we hope, especially seeing your data paired with the documentation. But you know us, always iterating, so let us know if you have suggestions on how we can improve our APIs.
  • http://whiteaway.com Mads Collin Nielsen

    Pretty awesome!

    A guide how to modify it into XML or JSON would be pretty amazing :)

    • allan

      All our APIs return JSON? We’re not planning on adding XML support, so there it will depend on what you are trying to consume it in.

  • Lauryn

    Thanks, and great call; solid feedback. :)