As a “serial Twitter app developer” I felt that it would be appropriate for me do a small series of articles on things I have learnt, some tips and the basics of what developing using the Twitter API involves. To start with I am going to talk about the basics and fundamentals of developing with the platform. But first and I am going to make a couple of assumptions:
- You know what Twitter is and are familiar with the terminology
- You know what a RESTful API is
Twitter has 2 different rate limits in place for IP addresses accessing the API. The standard rate limit is 150 requests per hour which can be enough for simple applications. But for apps that require more regular polling or requests that are started from a user visiting a page or running a script this simply isn’t enough. So you can get your application whitelisted, once approved (not more than 48 hours) you get 20,000 requests per hour. To get whitelisted Twitter has made a simple form. You must be logged in with the user that will be accessing the API and you need to list all servers that will be accessing the API.
It is always best to do this before you launch an app. I learnt the hard way with TwitterLeague (which I no longer operate) and had some unhappy users who couldn’t log in due to me hitting the rate limit for the hour after only a few minutes.
By “unauthenticated” I mean that you do not require a users login credentials to access the method. For instance getting a feed of the latest tweets from the public timeline, or getting a list of followers for a user who does not have their status set to private.
Sample PHP code for requesting the most recent tweets from the public timeline
//Initiate a curl session $ch = curl_init(); //Set the URL to the Public timeline curl_setopt($ch, CURLOPT_URL, "http://api.twitter.com/1/statuses/public_timeline.xml"); //Set a reasonable timeout of 5 seconds curl_setopt($ch, CURLOPT_TIMEOUT, 5); //Make sure we return all the data curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); //Put the contents into a variable $xml = curl_exec ($ch); //Close the curl session curl_close ($ch); //Print out the xml echo $xml;
These methods are great for applications that want to gather statistics and do not require users to sign up or have a customised user experience. For instance Twitter Grader is a site where you enter a username and every day from the time you enter your username it will gather statistics about the number of followers, number of tweets and an overall rank. This can then be analysed with lots of different filters like location or popularity etc. This can all be done because you don’t need to be authenticated to read someones tweets (if their account is not set to private).
Authentication is used for a couple of reaons. You either want to secure your data (we won’t get into an argument about basic authentication without SSL), or you want to have a personalised view. When you login to Twitter.com you see your tweets, your settings and your mentions etc. API authentication acts in the same way. If you want a web app that has an area for a user to login to, where they get a personalised page with data from the Twitter API, then you need to connect to the API as that person. That all make sense? If it did then you can read about the 2 types of authentication offered by Twitter.
Basic HTTP Authentication
When Twitter first announced their API back in 2007 they only had one method of authentication. This was Basic HTTP Authentication, which means sending a users username and password to let Twitter know you are requesting data on behalf of the user. This is great for Twitter clients like Tweetdeck and Tweetie because users are used to doing that with Instant Messenger clients etc. Beware that there are some big drawbacks.
With web apps it means that phishing is an issue. Any website could grab your Twitter credentials and take over your account and do a lot of damage.
The next biggest problem that Basic Auth brings is that it hides which user/application that’s sending tweets. This means that if an application gets your details and does malicious things with it, the only thing you can do is change your password and then go back to all the legitimate applications you use and update your credentials with them.
Sample PHP code for requesting a users direct messages
//Initiate a curl session $ch = curl_init(); //Set the URL to the Public timeline curl_setopt($ch, CURLOPT_URL, "http://api.twitter.com/1/direct_messages.xml"); //Add the users username/password (you will need to get this from the user) curl_setopt($ch, CURLOPT_USERPWD, "someusername:somepassword"); //Set a reasonable timeout of 5 seconds curl_setopt($ch, CURLOPT_TIMEOUT, 5); //Make sure we return all the data curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); //Put the contents into a variable $xml = curl_exec ($ch); //Close the curl session curl_close ($ch); //Print out the xml echo $xml;
If you don’t know what OAuth is please see this wikipedia article. There are 2 main advantages for users who authenticate using OAuth, the biggest being that they don’t have to enter their username and password into a third-party application because when authentication is needed the app redirects to Twitter.com so the user can enter their credentials there. When a user does this the application gets a couple of codes that are unique to that user and that application. This leads on to the second advantage. Because the codes given to the application are unique to the user and application it means Twitter knows who is sending tweets on the users’ behalf and therefore the users can remove a single applications access to their account without disrupting other applications access.
Future changes to the API roadmap
At Le Web 2009 Ryan Sarver from the Twitter Platform team gave us a preview of where the API will be going in the next year. There were a few changes to authentication. One of those was that there is going to be a 6 month deprecation of Basic Authentication. This is a big step and could well stop thousands of applications working. So they have done a couple of things to ease the transition:
- If you use OAuth authentication the user will have 10x the number of request available in their request limit
- You can use a persons username and password to get OAuth access tokens
So both of these points are encouraging you to start using OAuth as the only method of authentication for Twitter. It’s a great step forward to make Twitter more secure for their massive user base.
Ollie’s golden rule for authentication
Only use Basic auth if you absolutely have to. If you are doing a web app don’t use basic auth! Promise me!