Favstar.fm

Introduction

The Favstar API allows an app to embed a web view, and use OAuth Echo to identify the user. By passing an api_key you can identify your app, and Favstar will adjust user actions such as follow and fav to utilize your url scheme.

There's also an API for recording a Tweet of the Day which is becoming quite a popular feature.

Integrating the web view

If you're unfamiliar with OAuth Echo, Twitter has a page introducing it here: http://dev.twitter.com/pages/oauth_echo

Add these HTTP headers when Favstar is opened to initiate the session and pass the user's identity:

• X-Auth-Service-Provider - set to https://api.twitter.com/1/account/verify_credentials.json
• X-Verify-Credentials-Authorization - set to all of the oauth parameters as per Twitter's instructions
• X-Twitter-User-ID - Set to the user ID. After the first oauth request Favstar remembers the identified user in the session so it doesn't need to do the slow re-auth with each request. However, if your app allows for multiple users, Favstar needs to know if the selected user has changed. This header is compared with the user id in the session, and if it's different the new user goes through the authorization process with Twitter
• X-Favstar-API-Key - Obtain this from Favstar. It allows Favstar to identify your app and customize itself to suit your url scheme if you provide one.

Suggested URL scheme

To allow Favstar to integrate with your native experience, we recommend you provide urls for:

• Faving and unfaving a tweet
• Retweeting a tweet
• Replying to a tweet (open your window to write the tweet - accept an in_reply_to_id param)
• Write a new tweet, possibly passing default content.
• Following and unfollowing a user

Suggested integration points

Here are some suggested ways you can integrate Favstar into your app:

• View my own recent tweets.
  url: http://favstar.fm/users/[my user name]/recent
• View another user's most faved tweets.
  url: http://favstar.fm/users/[user name]
• View a specific tweet.
  url: http://favstar.fm/t/[tweet id]
• View another user's most retweeted tweets.
  url: http://favstar.fm/users/[user name]/most_retweeted

The Tweet of the Day API

Favstar's Tweet of the Day feature allows users to choose one tweet per day as Tweet of the Day. It's used as a way of rewarding the best tweet the users sees all day with a special acknowledgement. The tweet gets announced by @FavstarOfTheDay (or other accounts for Japanese, German, or Spanish Tweets), and it appears on the Tweet of the Day leaderboard page. It also gets tallied on the receiver's user page on Favstar.

Favstar provides an API for recording a Tweet of the Day selected by users.

The Tweet of the Day uses the same OAuth Echo parameters in the header to identify the user. To record a Tweet of the Day, post to the url http://favstar.fm/tweets/[tweet_id]/record_tweet_of_the_day

UI Suggestion: Don't show the option to reward Tweet of the Day to your own tweets or to private tweets.

Possible responses:

• Code: 200
  Sample Response:
  {
  "message" : "You have awarded @kyleve Tweet of the Day!",
  "recipient_user_id":14680556,
  "recipient_tweet_id":5060318324
  }
• Code: 403
  Sample Response:
  {
  "message" : "Sorry, you can't choose one of your own tweets as tweet of the day."
  }
• Code: 404
  Sample Response:
  {
  "message" : "Sorry, that tweet has either been deleted or is private, and can't be picked as Tweet of the Day."
  }
• Code: 409
  Sample Response:
  {
  "message" : "You've already chosen a tweet by @ev as your Tweet of the Day today. You can choose another one tomorrow. (in 3 hours from now)",
  "chosen_for_screen_name":"@ev",
  "chosen_for_user_id":20,
  "available_in_hours":3
  }
• Code: 402
  Sample Response:
  {
  "message" : "Tweet of the day lets you pick one tweet of the day to be announced by @FavstarOfTheDay. It's available as an bonus feature. Would you like to review the bonus features page to learn more?",
  "purchase_url":"http://favstar.fm/bonus_features"
  }