Better API documentation coupled with an explorer

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.

3 thoughts on “Better API documentation coupled with an explorer

    • 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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s