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 :idPOST /resources
=> create new resource using data given in request bodyPUT /resources/:id.:format
=> update resource with specified :id using data given in request bodyDELETE /resources/:id.:format
=> delete resource with specified :id and return resource in :format given
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.
