3 Great Tips to Improve Your API Status Pages

There are major advantages to today’s applications being built atop APIs. If you’re reading ProgrammableWeb, there’s a good chance you know all about integrating with other services. The major disadvantage of modern distributed architecture is pretty obvious—someone else’s service could go down and it’s outside of your control. You might not even know a service is down, which is why many top API providers are now making status pages available. These sites help communicate to developers when anything is amiss with the API.

Last week at SXSW, I was giving a workshop that leaned heavily on the Twitter API. Attendees started reporting strange errors and we eventually determined it was an API error. On the other side of the building, Twitter founder Biz Stone had it worse. A Twitter outage came during his Q&A, which included questions via Twitter.

I admit I didn’t look at the Twitter status page at the time. It’s likely the current performance section might have listed the outage. The recent performance section has no information for March 11, despite wide reports of an outage—or at the very least performance issues.

The goals of a good API status page

An API status page should communicate with developers about issues, both current and recent. Among the goals API providers should consider in a status page:

  • Be transparent
  • Be helpful
  • Be proactive

The absolute most important goal should be transparency. If a company’s API is down and that impacts a developer, that will in turn impact all of the developer’s users. As a developer, I’d want to have the information, because that could point me toward a solution.

Only if the status information I get is useful will I truly be able to figure out what to do. For example, Twitter breaks its API down by popular calls or services. More granular information is more helpful.

Finally, a good status page is proactive with the information it provides. Let’s say there’s a corrupt database that needs to be restored. In this fictitious example, a solution will take hours, not minutes, and the company should communicate to developers even when the news is bad.

Now that the goals of a good API status page are clear, let’s look at the tactics used by some of the most popular APIs.

Provide status updates

All the fancy charts, graphs and icons are great eye candy. Don’t get me wrong, infographics are useful, but at the most basic level you need to provide short, clear and human-understandable updates. This is best done with a simple list of textual updates. Some API providers create a special Twitter account and post even small issues to it.

Granular status updates achieve all three goals of API status pages. You can see an example from the Stripe API above. A number of individual updates can occur from the moment an issue is detected through its resolution. To be most clear, you might want to highly prioritize issues-of-the-moment, ongoing problems for which there might be many individual updates.

Show current API health

When developers come to a status page, they should be able to tell immediately whether it warrants further investigation. In other words, is the API healthy at this very moment?

Facebook puts current health information front and center, providing the current status, as well as when that status was reported. Also, the social network communicates the last time it pushed out changes to the API. And even better, you can get that data via an API call.

Stripe keeps it simple with a message at the top of its status page that even updates without reloading.

Twilio splits its current API health into its 22 services and shows past information alongside current status.

Look back on recent issues or downtime

For Be transparent and Be helpful, APIs should provide a historical look at API health. For example, details status information for the previous 24 hours might help a developer diagnose a problem that is no longer active. An API’s past downtime also tells would-be integrators what level of risk they’re taking on by using the API.

Facebook shows response time and error rate, averaged by the hour for the last 24 hours.

Stripe’s data goes back 90 days, color-coding days by length of downtime.

GitHub lets the data-hungry developer dig deep into its API status with seven charts available over the past day, week or month.

If developers are going to rely on an API, they need to know in as much detail how it is performing. API status pages, when done right, can communicate the API’s health at this moment and in the recent past. Further, they should help developers understand what is being done so that they know the API provider is being transparent, helpful and proactive.

If you’d like a glimpse of all the API status pages mentioned in this article in one giant file, you’re in luck. Just check out the giant version of the image above.

Adam DuVander is Developer Communications Director for SendGrid and Contributing Editor at ProgrammableWeb. Previously he edited this site and wrote for Wired. You can follow him on Twitter.

Be sure to read the next Best Practices article: Six Great Ways to Increase API Adoption