Twitter API's unRESTfulness causing trouble

Written on 11:07:00 AM by S. Potter

I am now designing my sixth (6th) set of web services on my new project. The previous five (5) and this current venture were/are for the purpose of allowing partners and internal developers to integrate with a "platform" of some kind. These clients varied from Fortune 500 companies, prestigious privately held firms and most recently a VC-funded startup. The previous two web service APIs were based on the REST "architecture" (yes, I know that word gets used too much, but I use it now for lack of a better word at this moment). The previous REST API was in fact fully RESTful and my new software product design also has the aim of RESTfulness at all points. During my travels meandering through the windy trails of designing REST APIs, I have realized just how important being truly RESTful is to REST APIs. Yes, reread that sentence again. if it doesn't make sense I recommend reading RESTful Web Services, which should clarify this distinction for you. For me, the biggest plus of RESTful web services is that it promotes consistency at all levels. Moving on...where was I going? Ah, yes, Twitter... The routes.rb for twitter.com seem to be a little misleading. It seems a mix and match approach was taken to developing a "RESTful" API for twitter.com using Rails. The current RESTful Rails convention is the following (in a nutshell):

• GET /resources/:id.:format => get information about resource with specified :id
• POST /resources => create new resource using data given in request body
• PUT /resources/:id.:format => update resource with specified :id using data given in request body
• DELETE /resources/:id.:format => delete resource with specified :id and return resource in :format given

This is all great, however, in twitter.com it seems there was a previous ugly step-child of a "RESTful" design implemented before Rails 1.2 standardized on the above approach (just speculating here). The evidence of this exists in multiple places in the Twitter API's inconsistency, however, one case in particular creates a defect in my view (and I am being kind by not considering all RESTful violations as defects, since the Twitter developers need to cater to the weekend PHP and VB.NET hackers that might not care about the beauty of REST's simple yet consistent design and purpose - I will give the Twitter developers the benefit of the doubt for this article): In the users#show API there seems to be a conflict. For example, GET /users/show.json?id=mylogin will, in fact, return the user information for user with screen_name ‘show’ instead of ‘mylogin’, which is obviously not the intention of the above HTTP call, especially when /users/show is an advertised way to access user information in the official Twitter API docs. Yes, I know I can call GET /users/mylogin.json and be done with it, but the misleading defect still remains. Interestingly, GET /users/show?id=mylogin does yield the expected result assuming you have the Accept HTTP header set to the appropriate mime-type (e.g. 'text/x-json'). Screen names that cause potential conflicts (if using Rails defaults) are: create, destroy, update, new, show. All of which exist at twitter.com. My point here isn't to blast Twitter developers necessarily, simply to ask all developers (or if you must title yourself this way "architects") to consider the importance of creating consistent APIs, preferably based on open standards/recommendations like REST. And most importantly, if a REST API isn't truly "RESTful", don't say it is!:) You will get more respect for being honest from people that know what it really means. Related post:

• Twitter4R v0.2.0 Released - the ultimate open source library that provides Ruby bindings for 100% of the officially documented Twitter REST API.

Posted in rails, REST, restful, twitter, web services

If you enjoyed this post Subscribe to our feed