Reading about the pending closure of the Yahoo! Photos and Yahoo! Auctions (in US, at least) services leads to an interesting question for those of us in the business of providing free APIs to our services.
What's the right way to decommission a Web Service API?
I suspect that since this is still a fairly new area, there aren't many "best practices" (I hate that term) established yet. And I further suspect that it's a bit more tricky that it might seem at first.
Consider the possibility that your REST-like service offers output in several formats (as some of Yahoo's do): XML, Serialized PHP, RSS, and JSON. And further assume that since the barriers to consumption are so low (no registration required), we can't possibly notify everyone in advance.
Clearly we ought to strive to shut things down in such a way that breaks people's code the least (code that we've never seen and can't influence). One line of thinking is that we pick a date and start returning the equivalent of an "empty set" for each response type. That means anyone using the results in a web site or application will have a chance to notice that something is wrong. But at some point we probably need to shutdown the actual endpoint. And when that happens, it'll generate a 404 error (or something similar) and possibly start to break things.
What do you think?
And, more importantly, is there any consensus on how to future proof libraries and code samples such that they can detect this in the future and fail more gracefully?
Oh, and I have a story about Yahoo! Auctions I should tell sometime soon...
Posted by jzawodn at May 10, 2007 01:23 PM