Early developer preview: Retweeting API
Marcel Molina
experience. It's yet another example of Twitter's users discovering
innovative ways to use the service. We dig it. So soon it's going to
become a natively supported feature on twitter.com. It's looking like
we're only weeks away from being ready to launch it on our end. We
wanted to show the community of platform developers the API we've
cooked up for retweeting so those who want to support it in their
applications would have enough time to have it ready by launch day. We
were planning on exposing a way for developers to create a retweet,
recognize retweets in your timeline and display them distinctively
amongst other tweets. We've also got APIs for several retweet
timelines: retweets you've created, retweets the users you're
following have created, and your tweets that have been retweeted by
others.
- Creating Retweets
The API documentation for creating retweets can be found here:
http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-retweet
Reminder: Making requests to /statuses/retweet won't work yet as the
feature has not launched.
- Consuming Retweets in the Timeline
1) Retweets in the new home timeline
We don't want to break existing apps that don't add retweeting support
or create a confusing experience for that app's users. So the
/statuses/friends_timeline API resource will remain unchanged--i.e.
retweets will *not* appear in it.
For those who *do* want to support retweets, we are adding a new (more
aptly named) /statuses/home_timeline resource. This *will* include
retweets. The /statuses/friends_timeline API resource will continue to
be supported in version 1 of the API. In version 2 it will go away and
be fully replaced by /statuses/home_timeline.
The API documentation for the home timeline, which includes retweets,
can be found here:
http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-home_timeline
Take a look at the example payload in the documentation. The original
tweet that was retweeted Thanks appears in the timeline. Notice the
embedded "retweet_details" element. It contains the user who created
the retweet as well as the date and time the retweet occurred.
2) Retweeted by me timeline
http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-retweeted_by_me
3) Retweeted to me timeline
http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-retweeted_to_me
4) My tweets, retweeted
http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-retweets_of_me
Reminder: Making requests to any of these timelines won't work yet as
the feature has not launched.
UI considerations:
------------------
Here are some early draft design mockups of how retweets might appear
on the Twitter website (don't be surprised if
it doesn't look exactly like this). They are presented just as an
example of how retweets can be differentiated visually.
http://s.twimg.com/retweet-dev-mocks-7-aug-09.png
Things to note:
1) It was important for us that retweets are easily differentiated
visually from regular tweets. If someone you follow retweets a tweet,
the original tweet will appear in your timeline whether you follow the
author of the original tweet or not, just as it currently does when
users use the "RT" convention. Seeing a tweet in your timeline from
someone you don't follow without being told it was shared from someone
you *do* follow could be confusing. So we're encouraging developers to
be mindful of this confusion and make retweets stand out visually from
regular tweets.
2) The retweeted tweet shows the username of the first of your
followers to retweet it. If other's subsequently retweet the same
tweet, the retweet should only appear once in a user's timeline
That's it for now.
We'll be sending out more updates as we get closer to launching.
--
Marcel Molina
Twitter Platform Team
http://twitter.com/noradio