I found some unexpected wisdom, along with a lot of things I agree with.
"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."
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.
BBC (I think or maybe it was PBS|NPR) did this. Recent article talked about how they decided to go "open" and put everything in API. Later on when developing for satelite stations and other projects they found using their API was the bestest, fastest way to go.
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.
Chances are that they've got something like HAProxy running in front of their application backends, and you get a shirnkwrapped 503 page back when no backend can be reached. In that case, the application can't intelligently decide to return a json response because the application never gets the request.
While API clients should be able to interpret the HTTP response code, 503 in this case, in a meaningful way, the API should have internal status/success codes that the body of the 5xx responses can contain.
Using haproxy to load balancer is no excuse for this, as you can tell haproxy to serve custom error documents using the errorfile option, and these error documents can be json or XML. And you can use layer 7 routing in haproxy to allow different configurations based on what the request looks like (in the case of, say, you were dumb and put everything your site does on a single domain, rather than putting the api on a different IP/subdomain).
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.
I wish more services would implement open protocols, agreed upon standards than just proprietary APIs.
It should be noted that in general APIs are a modern form of slavery!
I think that's a little over the top, nobody is forcing anyone to use their API. If you rely on an API, you should accept that it can (and likely will) change in the future.
Twitter has been pretty up front about the fact that HTTP Basic would be shut off since they first released OAuth. I think they've done just about as much as they can to help people move away from HTTP Basic.
I wish more services would implement open protocols, agreed upon standards than just proprietary APIs.
I'm not sure what you mean by open protocols and agreed upon standards. HTTP Basic and OAuth are both open and agreed upon.
"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."
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.