Thursday, May 3, 2012

We reserve the right to refuse this web service to anyone.

Do you use a web API as part of your product? Perhaps you let users login and find friends using a Social API, show users information using a Geolocation API tied to a Mapping API, save user images/video/audio using a Storage API translated with a Translation API, etc…

If you clicked on any of the Web API links in the previous paragraph, then I apologize because none of those APIs work any more. They’re all dead.

If your product did rely on any of those APIs, how would your product fare?

Assertion: Every Web API will someday fail you


Relying on a third party API provides a lot of power very quickly. But keep in mind that the Terms-Of-Service for every 3rd-party Web API goes something like this.

EVERY Web API Terms of Service (TOS)

We reserve the right to refuse this web service to anyone…
…at any time…
…for any length of time…
…for any reason…
…or for no reason at all…
…and to change these or any other terms of service…
…or to change our APIs…
…or to change our pricing…
…or to add limits to your usage…
…or to give away whatever information you send us…
…or to just screw up and stop working…
…or to go belly up…
…or to get bored and stop paying attention...
…at any time.

I can promise you that any Web API you use, or any Web API you create, will, at some point in the future, be different than it is today (i.e. however you use it now, it will someday “break”). I just took a brief tour of programmableweb api directory, and out of 10 mashups I tried at random, only 3 were currently working. Out of 5814 APIs, 602 are listed in the deadpool (about 10%) but randomly picking 10 of those that were not in the deadpool only 5 were still alive. Some of these broken APIs are from tiny little companies I’ve never heard of, and others are from the biggest internet companies of all.

In just the past year I have been personally involved in products that failed in full or in part because a web API they relied on was shut down or changed. In the past year I have personally shut down a service that provided a Web API, causing the apps that relied on that service to become useless.

Web APIs are unreliable.

If Web APIs are so unreliable, should I use them?

If a Web API enables you to build a better product, and to build it faster, then, yes, use the Web API. But use that API in full knowledge that it won’t always work as it does today. Someday it almost certainly will not work at all.

What’s a reliable strategy for using unreliable Web APIs?

The most important step for dependency on 3rd-party APIs is to admit that you are powerless over them, and to accept that they are unreliable. Once you accept that fact, the other steps follow.
  • For every Web API you use, determine whether it is core or supplementary to your product (i.e. is your product totally useless without that service). In the following issues you’ll probably have different answers for core vs. supplementary services.
  • For every Web API you use, create three levels of fallback plans for what should happen when those services fail:
    1. If the service is unavailable temporarily, for just a few seconds, decide where you stand on these questions: Will your fallback simply retry a few times? Will the user still be able to use parts of your product? Will the user have any idea what’s going on?
    2. If the service is unavailable for many seconds/minutes/hours, define what should happen: How will the user be informed? Will your product be totally useless? Note that it is OK to choose that your product to be useless for a while, so long as you have thoughtfully made that decision—if this happens, you must not keep your users in the dark; they must be provided with information, even if it’s just something like “sorry, we’re suffering right now, see http://oursite.com/suffering for more information”.
    3. Assuming you’ve taken care of 1 and 2, you’re in good shape to plan what should happen if the web service goes away forever, or if it’s pricing changes radically.
  • Having determined these fallback plans, provide easy ways to disable Web APIs frequently during development and testing, and to verify that they behave according to your fallback plans (for brief, temporary, and long-term failures). These service-outage simulations should be part of a regular regressive test procedure.
  • Bonus assignment for the best students: Add kill-switches for every service you rely on, so that if they are behaving extremely poorly you can step in quickly to prevent your users from suffering consequences of a bad service that is beyond your control.
  • Check if the Web API provider has a clear deprecation policy (they should) and regularly check up on this so you have a long time to prepare. You cannot guarantee that they’ll follow the policy, but this will help you be prepared.
  • If the Web API means that your important data will be in their systems, verify how to periodically retrieve that data so that you have it for when their service fails and you need to switch.
You can and probably should use 3rd-party web APIs, but rely on them being unreliable.

Today’s Takeaway: Every Web API will sometimes fail--someday it will fail forever. Plan for those failures. Practice your plan.

No comments:

Post a Comment