Updates to the retweet API payload

We've updated the retweet payload to look a lot more like a regular
tweet's payload. We find this change makes the retweet API
conceptually simpler, easier and more convenient to work with and
better overall. I've linked to examples of the new payload below, and
will be updating documentation shortly, but first I'd like to share
some background on what we've learned working on the retweet API over
the past few weeks.

One of the big objectives of the retweet feature is discovering new
users to follow. We wanted the original status and its author
highlighted front and center so they get due credit for the tweet
someone you follow found worthy of retweeting. To that end the API was
designed to emphasize the original tweet by having it be the top level
object. Embedded within it we provided details about who retweeted it
and when.

Though this makes a statement to how we'd like the feature to be
thought about, logistically it doesn't degrade gracefully for clients
who don't implement any retweet logic in their code. Tweets appear in
timelines from people who you do not follow and unless clients
differentiate those tweets visually letting you know that someone you
follow has shared this tweet, confusion ensues.

To mitigate this, we opted to not include retweets into the existing
friends timeline. Instead we created a new parallel home timeline that
would be just like the friends timeline but included retweets. That
way developers could opt in to the retweet feature at their leisure.
Even with this opt in policy, though, there is still a critical
responsibility imposed on developers to clearly communicate to their
users that a given tweet in their timeline is a retweet and who the
retweet is from. The likelihood that confusion would result turned out
to be too high.

Additionally, with the original status as the top level object in the
payload, that means consumers of the API would receive what appears to
be the same tweet multiple times. In a lot of cases that's fine, in
others it's problematic.

After experimenting with this approach we've decided that it's a
better bet to craft a payload that will degrade far more gracefully.
So we've redesigned the retweet payload. Rather than having the
original tweet as the top level status with embedded details about who
retweeted it, the retweet is the top level object and within it we
include the original tweet and its author. You'll have full access to
the entire retweeted status and user as well as the original tweet and
its user. So you don't have to make any additional API calls and
should have everything you need to display a retweet distinctively
with attribute to both the original author and the retweeter. In other
words, these retweeted statuses look a whole lot like regular
statuses. This new design was our instinct to begin with and we
probably should have gone with it. We think it's better and hope you
do too. All the same documented resources will exist. Only the
payloads change.

The following timeline should contain examples of the updated retweet
payload. You can use this to test consuming retweets.
curl http://twitter.com/statuses/user_timeline/testiverse.xml
curl http://twitter.com/statuses/user_timeline/testiverse.json

In the event that new tweets go into the above timeline that push the
retweets out, you can access a few directly at the following urls:
curl http://twitter.com/statuses/show/4452134416.xml
curl http://twitter.com/statuses/show/4452466408.xml
curl http://twitter.com/statuses/show/4349744308.xml

The above payloads don't contain a "retweet_count" element yet and
they probably will. Other than that we don't suspect any more major
changes as we approach a full public launch. As always, though, we're
open and solicitous of everyone's feedback.

Thanks.

--
Marcel Molina
Twitter Platform Team
http://twitter.com/noradio