I found some unexpected wisdom, along with a lot of things I agree with.<p>"If you haven't built your website on top of your API, consider doing that -- or at least what it would be LIKE to do that. If your API couldn't reproduce your website, your API needs fixing."<p>At first, I was going to argue with this. But then I realized: You don't have to actually -do- it, just write like you would. You don't have to give third parties the ability to do everything you can do locally, so long as you program in such a way that it can be done. It helps decouple things better, and make things more testable.
Twitter is the absolute best case study for this. I love that a response that should return XML or JSON formatted data returns the fail whale in all its HTML glory when they're overloaded. I still don't understand how in their mind that's more efficient than a 503 http response.
Oh man, I wish the developers of the API I'm working with right now read this (or just had any common sense at all). XML feed is a load of tab seperated data held in one tag. Two, three or four API calls are needed to get all the data I require (using unique codes from previous calls so there's no other way) and when it sees something unexpected, as it wont to do since I'm passing a tab-seperated mass of meaningless codes, it just dumps back the XML you sent it. No error message, no stack trace - just exactly what you sent over before. Kind of like a teacher handing you back some work with the "want to try again?" speech.
It should be noted that in general APIs are a modern form of slavery! Build something that depends on an API, and be exposed to any arbitrary decision by this API provider. I think Twitter's decision to shut down HTTP basic Auth (in favor of OAuth, which is great) is a perfect example of this.<p>I wish more services would implement open protocols, agreed upon standards than just proprietary APIs.