

Twitter’s poor API documentation practices - idan
http://gazit.me/2012/01/09/Twitter-documentation-fail.html

======
ComputerGuru
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=...](https://developers.facebook.com/bugs/285421101492706?browse=search_4f0b662b147b41994400672)

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

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

~~~
kingofspain
Ugh. I did a favour for someone by added some _very_ basic FB integration to
his site. I've had to go back 2 or 3 times to fix it and he now thinks I'm
pretty incompetent as a result.

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

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

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

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

------
flyosity
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
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?

------
mkopinsky
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
hear, hear

------
jroseattle
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
I look forward to seeing your perfectly-documented API product.

~~~
jroseattle
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."

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

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

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

------
jenius
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?

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

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

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

------
ovechtrick
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!

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

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

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

------
semisight
Oh god. I'm going to be working with that? _sobs_

