For instance, Facebook. For months now, the Like button has been completely broken on any sites that classify themselves as og:type product. Which is basically, very many indeed.
The bug? Some idiot at Facebook apparently registered type "product" as belonging to a particular app id. Now no one other than this unknown entity is allowed to use og:type product.
The problem is, it could be easily argued that the single-most feature of the facebook API is the like button. If the very core of their "business" is so overwhelmingly neglected and broken from an API perspective, how can anyone trust them to do anything right after that? How can anyone feel comfortable building on the Facebook platform, basing the existence of entire products, startups, and companies on the whim of such a ridiculously unorganized company and their broken API?
The age of web apps is great, but you cannot blame anyone for lamenting the end of an era where your products were as good as your code - not reliant on the whims and caprices of a company that you can't trust to maintain their API - or even build it right in the first place.
Facebook has 'acknowledged' the issue, but what's the use of that?
They've even faffed with the basic generated widgets enough for you to have to keep an eye on what works, so you can prepare to fill the same form in yet again to get the same thing working again.
Stability should be the priority if you don't want to piss third party devs off.
A more exhaustive index of the fields, a kind of bird watcher's guide for the fields of the Twitter API, should make an appearance in the coming weeks.
Clearly he hasn't worked enough with Facebook's API and its often broken documentation. It's always fun when Facebook decides to change the API when you're in the middle of a project, but keep backwards compatibility and only "hide" the documentation for the old API so you can't find it with search, and now you're left with trying to decide if you should try to keep using the old interface or change your whole code for the new API.
I had many late nights trying to debug similar problems. One particular problem I never solved was using the language/location information to help filter out invalid tweets in non English tweets.
I used C# to do the processing and eventually gave up trying to cast the JSON from their API to static types and used C#'s dynamic keyword as their documentation was so poorly written and didn't include decent examples.
Are you validating responses now, or just assuming they'll never change / always be correct?
That's a pretty big "yada yada yada" you left out. I am going to assume there's a legit reason why getting a string back instead of another type of reason crippled your servers, but I'd like to know what it was.
We are developers creating a product (an API) for other developers. We know what other developers are going to want to understand and the details they're going to need when implementing against an API. It should be crystal clear what information needs to be provided.
Maybe we should just pat Twitter, Facebook, etc. on the back for what they provide and say "hey guys, appreciate the almost-accurate info."
In general APIs are going to suck unless you're paying to access them. It may be less than perfect, but being able to ride on the coattails is better than nothing.
If you ever tried Facebook API ... People complain that there are no examples for Facebook API: the problem is that they cannot keep up with example to work with constant changes, so they just gave up on examples.
The timeline returned is the equivalent of the one seen when you view a user's profile on twitter.com.
- the value is capped at 100 (since the retweet count is displayed up to 100)
- the value can be "100+" (https://twitter.com/#!/SEGA/status/144219968773423104 says "Retweeted by ivucica and 100+ others")
Now, I don't disagree that the documentation should explain retweet_count more clearly, but I'm surprised that people trip up on this particular issue.
Clearly I should have read it the other way - but I bet a lot of people will read it like I did.
I think what they really need is to figure out what calls people make most often and mark those very clearly at the top, along with a human-readable description. Like for example "HERE'S THE CALL YOU CAN USE TO GET A USER'S TWEETS', or 'HERE'S THE ONE YOU USE TO GET TWEETS ABOUT WORD OR HASHTAG X' -- Isn't this the case for everything?
Twitter supplying a torture test might make more of a difference -- I don't know.
Just listing methods that some programtic tool created is not documenting an API.
I'd love to see this article rewritten:Facebook API edition!