Twitter’s poor API documentation practices

http://gazit.me/2012/01/09/Twitter-documentation-fail.html

by idan • 15 years ago

166 39 15 years ago

leviathan• 15 years ago

From the article: "Of all the large product API’s I consume regularly, Twitter’s is the one I’ve had the worst experience with. "

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.

ComputerGuru• 15 years ago

I'll take a poorly documented API that works over an API so broken, that's its outright ludicrous.

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.

https://developers.facebook.com/bugs/285421101492706?browse=...

Facebook has 'acknowledged' the issue, but what's the use of that?

jlogsdon• 15 years ago

Facebook's API is notoriously bad, and they love to update it with breaking changes all the time without any notification or change to the documentation. It was a great day when I stopped working with it.

ovechtrick2• 15 years ago

I'm pretty sure several of my gray hairs can be attributed to the facebook API.

bkaid• 15 years ago

Facebook API had so many breaking changes happening all the time that they decided, as a "benefit" to developers, that they would stack them all up to occur on the first of each month. This is in the name of BS called "operation developer love". And this is only for the breaking changes that get announced. The much more common scenario that ComputerGuru mentions is where stuff gets broken, acknowledged as a bug Facebook, and then never fixed. If you read the stats they publish in their blog posts, 2-3x the number of bugs get accepted than the number that get fixed, EVERY SINGLE week.

FuzzyDunlop• 15 years ago

I read this and I think, why would I even want to write code for an API that I'd have to maintain far more actively than the rest of my project?

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.

lrobb• 15 years ago

My favorites were bugs filed where numerous people would post about it, fb would never respond, then after a few months they would just "close" it due to inactivity!

Mind-boggling.

matwood• 15 years ago

I wonder if FB (and Google for that matter) are starting to suffer from their hiring that slants towards young recent college grads. All the cool kids only want to work on and build new things. Fixing bugs, cleaning code up, making it professional, etc... is for someone else to do. The problem is that 'someone else' doesn't really exist in those companies.

flyosity• 15 years ago

Ha, this exact issue bit us in the ass a few months ago. We were working on some streaming Twitter utilities (put in a username and we fire off some events if a mention or a RT of them occurs) and just to test the scalability of our services we entered Justin Bieber. Well one of his tweets got over 100 RTs fairly quickly and we weren't expecting a string to come back. Long story short, it solidly fucked up our event queueing/processing pipeline and brought some of our servers to their knees.

Thanks, Twitter!

polemic• 15 years ago

Really? An expected response from a foreign (uncontrolled) source brought you servers down?

Are you validating responses now, or just assuming they'll never change / always be correct?

azth• 15 years ago

Hooray for type safety?

sutterbomb• 15 years ago

Yup same issue bit me once too - sorting tweets by their RT count doesn't work well when the count is no longer an integer. (Fortunately I was only building a little app for myself to try to learn Ruby and Sinatra.)

mattdeboard• 15 years ago

"Well, we got a string instead of an integer and yada yada yada, our network almost collapsed."

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.

ac2u• 15 years ago

Not alone in testing a heavy stream of tweets using "Bieber" then!

philjones88• 15 years ago

I had the misfortune of doing my final year computing dissertation using Twitter's streaming 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.

Fond memories.

veyron• 15 years ago

The problem with his example `retweet_count` is the blanket statement in the API:

    The timeline returned is the equivalent of the one seen when you view a user's profile on twitter.com.

Thus:

- 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.

nmcfarl• 15 years ago

Now I don't use twitter's API, so I have no clue as to their conventions, but when I saw, in the documentation you qouted, the phrase the "equivalent of", I read this as the "raw data we used to produce" , and not the "exact string you see."

Clearly I should have read it the other way - but I bet a lot of people will read it like I did.

stilist• 15 years ago

You shouldn’t have to reverse-engineer a service to compensate for documentation gaps.

pdenya• 15 years ago

"Of all the large product API’s I consume regularly, Twitter’s is the one I’ve had the worst experience with." - I hope you never have to deal with facebook.

slig• 15 years ago

Like twitter gives a shit about the API. See if you can get your own old tweets or DMs.

episod• 15 years ago

As someone who writes a bit of documentation for dev.twitter.com, I admit that a full accounting of every field that passes through the API is certainly missing. The reasons are boring and mostly historical, related to the organic growth of the API & its documentation; for much of the existence of the API, deep pre-existing understanding of Twitter itself was assumed and required for success. That combined with the majority of developers using scripting languages with loose typing meant that devs could fill in the blanks pretty easily.

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.

semisight• 15 years ago

Oh god. I'm going to be working with that? sobs

chaostheory• 15 years ago

I think this is an industry wide problem, and not just Twitters. It's more the norm to see bad or incomplete documentation than to see stellar, up to date docs.

dudus• 15 years ago

Ok So you found 1 missing line of comment on the API docs for twitter. Suddenly the whole API doc is garbage. You do a very good job generalizing.

jroseattle2• 15 years ago

I just do not understand why documentation continues to be a problem. There are plenty of API-as-platform models going around, and there will be more in the future.

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.

bentlegen• 15 years ago

I look forward to seeing your perfectly-documented API product.

jroseattle2• 15 years ago

Why strive for quality, eh?

Maybe we should just pat Twitter, Facebook, etc. on the back for what they provide and say "hey guys, appreciate the almost-accurate info."

jenius• 15 years ago

I just recently was impressed by how nice looking their docs are and confused by how bad they are at actually explaining what to do with it, so I can certainly relate.

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?

abecedarius• 15 years ago

While, yes, docs should actually document all of the cases, this post just assumes developers will actually read the docs and cover all the cases. Would be nice.

Twitter supplying a torture test might make more of a difference -- I don't know.

zerostar07• 15 years ago

By analogy, we have to expect the author to write a 800-page tome when he gets his hands on Facebook's elusive API.

tlogan• 15 years ago

I don't know, Twitter API at least works in consistent manner.

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.

dpeck• 15 years ago

My experience is similar to a lot of others. I've spent the last two years working with quite a few social media APIs and while Twitters API documentation and reliability could be a bit better at least it looks like there was some level of design/thought to it. On the other hand is Facebook, which to say appears to have come into existence organically would be beyond generous. Examples are non existent, bugs are either unacknowledge or unfixed indefinitely and documentation as simple as what permissions are needed to access a property are a challenge to find.

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.

Tichy2• 15 years ago

Um, isn't that simply a small bug in the documentation that should be reported to Twitter, not blown out of proportion in a blog post?

mjwalshe• 15 years ago

No abysmal documentation is I am afraid endemic these days look at the mess that is googles API's

Just listing methods that some programtic tool created is not documenting an API.

Tichy2• 15 years ago

Sure, I was only referring to the linked article which seems to dwell on a single undocumented field in the API.

ovechtrick2• 15 years ago

I absolutely feel this authors pain. I laughed out loud the entire time reading this.

I'd love to see this article rewritten:Facebook API edition!

mkopinsky• 15 years ago

Am I the only one getting tired of articles on Hacker News amounting to, "$PRODUCT is horribly broken! Let me describe one small pain point and promise you that there are countless others."?

kijun• 15 years ago

hear, hear

Twitter’s poor API documentation practices

Related Stories