The Design of the Twitter REST API

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 GET
Get a user statuses GET GET
Get a particular status GET GET
Create a new status POST POST
Authorization: Basic xxxx
<status>my status message</status>
Delete a particular status DELETE/ POST DELETE
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
Get a particular user statuses GET{user_id}/statuses.xml
Get a particular statuses of a user GET{user_id}/statuses/{status_id}.xml
Crete a particular statuses of a user POST{user_id}/statuses.xml
Update a particular statuses of a user PUT{user_id}/statuses/{status_id}.xml
Delete a particular statuses of a user DELETE{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.

This entry was posted in REST, RESTful and tagged , , , , . Bookmark the permalink.

4 Responses to The Design of the Twitter REST API

  1. JakaJancar says:

    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

    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.

  2. dimuthu says:

    Hi Jaka Janncer,
    I don’t think we can put all the restrictions in filter inside a URL. I would prefer to use


    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,

  3. 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.

  4. dimuthu says:

    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.


Leave a Reply

Your email address will not be published. Required fields are marked *