The objective of this blog post is to explore in detail the patterns and practices Twitter has used in it’s API management.
Twitter comes with a comprehensive set of REST APIs to let client apps talk to Twitter.
Let’s take few examples…
If you use following with cUrl – it returns the 20 most recent statuses, including retweets if they exist, from non-protected users. The public timeline is cached for 60 seconds. Requesting more frequently than that will not return any more data, and will count against your rate limit usage.
curl https://api.twitter.com/1/statuses/public_timeline.json
The example above is an open API – which requires no authentication from the client who accesses it. But keep in mind… it has a throttling policy associated with the API. That is the rate limit. For example the throttling policy associated with the ..statuses/public_timeline.json API could say, only allow maximum 20 API calls from the same IP address.. like wise.. so.. this policy is a global policy for this API.
1. Twitter has open APIs – where anonymous users can access.
2. Twitter has globally defined policies per API.
Let’s take another sample API – statuses/retweeted_by_user – returns the 20 most recent retweets posted by the specified user – given that the user’s timeline is not protected. This is also another open API.
But, what if I want to post to my twitter account? I could use the API statuses/update. This updates the authenticating user’s status and this is not an open API. Only the authenticated users can access this.
How do we authenticate our selves to access the Twitter API?
Twitter supported two methods. One way is to use BasicAuth over HTTPS and the other way is OAuth 1.0a.
BasicAuth support was removed recently and now the only remaining way is with OAuth 1.0a. As of this writing Twitter doesn’t support OAuth 2.0.
Why I need to use the APIs exposed by Twitter – is that I have some external applications that do want to talk to Twitter and these applications use the Twitter APIs for communication.
If I am the application developer – following are the steps I need to follow to build my application to access protected APIs from Twitter.
First the application developer needs to login to Twitter and creates an Application.
Here, the Application is an abstraction for a set of protected APIs Twitter exposes outside.
Each Application you create, needs to define the level of access it needs to those underling APIs. There are three values to pick from.
– Read only
– Read and Write
– Read, Write and Access direct messages
Let’s see what these values mean…
If you pick ‘Read only’ – that means a user who is going to use your Application needs to give it the permission to read. In other words – the user will be giving access to invoke the APIs defined here which starts with GET, against his Twitter account. The only exception is Direct Messages APIs – with Read only your Application won’t have access to a given user’s Direct Messages – even GETs.
Even you who develop the application – the above is valid for you too as well. If you want to give your application, access your Twitter account – there also you should give the application the required rights.
If you pick Read and Write – that means a user who is going to use your application needs to give it the permission to read and write. In other words – the user will be giving access to invoke the APIs defined here which starts with GET or POST, against his Twitter account. The only exception is Direct Messages APIs – with Read and Write, your application won’t have access to a given user’s Direct Messages – even GETs or POSTs.
3. Twitter has an Application concept that groups APIs together.
4. Each API declares the actions those do support. GET or POST
5. Each Application has a required access level for it to function[Read only, Read and Write, Read Write and Direct Messages]
Now lets dig in to the run-time aspects of this. I am going to skip OAuth related details here purposely for clarity.
For our Application to access the Twitter APIs – it needs a key. Let’s name it as API_KEY [if you know OAuth – this is equivalent to the access_token]. Say I want to use this Application. First I need to go to Twitter and need to generate an API_KEY to access this Application. Although there are multiple APIs wrapped in the Application – I only need a single API_KEY.
6. API_KEY is per user per Application[a collection of APIs].
When I generate the API_KEY – I can specify what level of access I am going to give to that API_KEY – Read Only, Read & Write or Read, Write & Direct Message. Based on the access level I can generate my API_KEY.
7. API_KEY carries permissions to the underlying APIs.
Now I give my API_KEY to the Application. Say it tries to POST to my Twitter time-line. That request also should include the API_KEY. Now once the Twitter gets the request – looking at the API_KEY it will identify the Application is trying to POST to ‘my’ time-line. Also it will check whether the API_KEY has Read & Write permissions – if so it will let the Application post to my Twitter time-line.
If the Application tries to read my Direct Messages using the same API_KEY I gave it – then Twitter will detect that the API_KEY doesn’t have Read, Write & Direct Message permission and the request will fail.
Even in the above case, if the Application tries to post to the Application Developer’s Twitter account – there also it needs an API_KEY – from the Application Developer, which he can get from Twitter.
Once user grants access to an Application by it’s API_KEY – during the entire life time of the key, the application can access his account. But, if the user wants to revoke the key, Twitter provides a way to do that as well. Basically when you go here, it displays all the Applications you have given permissions to access your Twitter account – if you want, you can revoke access from there.
8. Twitter lets users revoke API_KEYs
Also another interesting thing is how Twitter does API versioning. If you carefully look at the URLs, you will notice that the version number is included in the URL it self -https://api.twitter.com/1/statuses/public_timeline.json. But it does not let Application developers to pick, which versions of the APIs they want to use.
9. Twitter tracks API versions in runtime.
10.Twitter does not let Application developers to pick API versions at the time he designs it.
Twitter also has a way of monitoring the
status of the API. Following shows a screenshot of it.
11. Twitter does API monitoring in runtime.
Reference: The Twitter API Management Model from our JCG partner Prabath Siriwardena at the Facile Login blog.
