The REST API for Twitter is very simple to learn and implement. And it has a comprehensive documentation.
Here is some selected operations to just to show its design. Note that here userid should be replaced with a valid twitter user id or user name and the format should be changed to the required output format (.xml, json, rss, atom are possible output formats)
| Operation | HTTP Verb | URL | Example HTTP Request (Setting username as ‘dimuthu’ and the output format as .xml) |
| Get public (all users) statuses | GET | http://twitter.com/statuses/public_timeline | GET http://twitter.com/statuses/public_timeline |
| Get a user statuses | GET | http://twitter.com/statuses/user_timeline/userid.format | GET http://twitter.com/statuses/user_timeline/dimuthu.xml |
| Get a particular status | GET | http://twitter.com/statuses/show/statusid.format | GET http://twitter.com/statuses/show/938135815.xml |
| Create a new status | POST | http://twitter.com/statuses/update.format | POST http://twitter.com/statuses/update.xml Authorization: Basic xxxx ……….. <status>my status message</status> |
| Delete a particular status | DELETE/ POST | http://twitter.com/statuses/destroy/statusid.xml | DELETE http://twitter.com/statuses/destroy/939390294.xml Authorization: Basic xxxx ……….. |
After having look at this API, the first question I had was whether this API is actually RESTful. In RESTful design we expect to map a resource to a URL and do CRUD (Create, Read, Update and Delete) operations using request with different Http Verbs (POST, GET, PUT, DELETE) with that same URL. Look at my blog on RESTful CRUD Data Services Demo for more clarification.
So if ever the API is designed following the above theory it would have been like this.
| Operation | HTTP Request |
| Get all statuses | GET http://twitter.com/statuses.xml |
| Get a particular user statuses | GET http://twitter.com/users/{user_id}/statuses.xml |
| Get a particular statuses of a user | GET http://twitter.com/users/{user_id}/statuses/{status_id}.xml |
| Crete a particular statuses of a user | POST http://twitter.com/users/{user_id}/statuses.xml |
| Update a particular statuses of a user | PUT http://twitter.com/users/{user_id}/statuses/{status_id}.xml |
| Delete a particular statuses of a user | DELETE http://twitter.com/users/{user_id}/statuses/{status_id}.xml |
So I think although Twitter API is really nice and easy, it is not really a RESTful API. If it was really RESTful, URLs might have been more organized so more easier to remember or predict. But still this API allows thousands of third party application to talk to the twitter, demonstrating the value of providing web services over just providing some web pages in a website.
A bit late and off-topic, but since you’re “waiting for our comments”, what the heck 🙂
How would you RESTfully design searching (filtering), ordering and pagination?
Sometimes filtering can be done nicely via “sub-resources”, like /users/{user_id}/statuses.xml in the Twitter API, but this won’t work for multiple filters or filters with ranges, etc.
Would you use some ugliness like
/statuses.xml?filters[user]={user_id}&filters[born][from]=1970&filters[born][to]=1980
?
When (if at all), philosophically, do you think are query params permissible in RESTful APIs?
BTW: Are there any good APIs that actually _ARE_ RESTful out there to use for reference? Seems Twitter only comes close, Flickr and Facebook think REST is XML-RPC, etc.
Hi Jaka Janncer,
I don’t think we can put all the restrictions in filter inside a URL. I would prefer to use
/users/{user_id}/statuses.xml?filters[born][from]=1970&filters[born][to]=1980
I think the idea is to assign a URL to a resource and do CRUD operation around that. And when we do GET, we may need to do some filtering with query parameters of the url, (which we don’t use for post or put obviously)
Well, I have read it is ok to put query params in the RESTful API.(But I’m not sure whether it is ok to the philosophy :). At least we have to use it for filtering as you told.
Among the available public APIs, I also think twitter is far more RESTful. There are frameworks that help to write RESTful web services, which should be used in lot of places (but not sure the public availability). At least there are some theoretical scenarios available, http://www.infoq.com/articles/webber-rest-workflow.
Hi dimuthu,
Very intere
I don’t see anything wrong with putting the filter params in the URL. Another approach is set your filter params in a custom header of that request.
Do you guys think that setting the response format (eg. url/status.xml) in the URI is the right thing to do (RESTful)? I had a blog post on why you shouldn’t do that. And I am really interested to know your thoughts about it. I am starting to see it in more and more APIs — and I am not sure why architects choose this design decision.
Here is the post URI. http://www.khussein.com/how-to-design-a-restful-api/
Hi Khaled,
I agree most of the time filter params can be embedded within a url. But I think in a complex set of filters we better adapt query params. Let say we say we designed a url like this.
books/author/{author}/published/{published-year}/publisher/{publisher} -[1]
Instead I would have prefered,
books?author={author}&published={published-year}&publisher={publisher} -[2]
Although you can say the url[1] mapped to a particular set of resources, when you drop 1 or 2 filter (author or publisher) it become a completely different url, but with url[2], it is not strange to drop some filters.
This is just my thoughts. Probably you may not see any wrong there.
And as you said, a client can use Accpet header to request server the response format/media type. I also haven’t see that is used much, probably because not much REST frameworks are not supporting that.
Thanks for sharing your thoughts.
Thanks
Dimuthu