Comments on: The Design of the Twitter REST API http://www.dimuthu.org/blog/2008/09/29/the-design-of-the-twitter-rest-api/ Waiting for your comments Mon, 15 Mar 2010 02:10:31 +0000 http://wordpress.org/?v=2.9.2 hourly 1 By: dimuthu http://www.dimuthu.org/blog/2008/09/29/the-design-of-the-twitter-rest-api/comment-page-1/#comment-11789 dimuthu Sat, 22 Aug 2009 17:24:40 +0000 http://www.dimuthu.org/?p=408#comment-11789 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 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

]]> By: Khaled Hussein http://www.dimuthu.org/blog/2008/09/29/the-design-of-the-twitter-rest-api/comment-page-1/#comment-11787 Khaled Hussein Sat, 22 Aug 2009 16:20:48 +0000 http://www.dimuthu.org/?p=408#comment-11787 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 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/

]]> By: dimuthu http://www.dimuthu.org/blog/2008/09/29/the-design-of-the-twitter-rest-api/comment-page-1/#comment-4281 dimuthu Thu, 05 Mar 2009 03:02:55 +0000 http://www.dimuthu.org/?p=408#comment-4281 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, <a href="http://www.infoq.com/articles/webber-rest-workflow" rel="nofollow">http://www.infoq.com/articles/webber-rest-workflow</a>. 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.

]]> By: JakaJancar http://www.dimuthu.org/blog/2008/09/29/the-design-of-the-twitter-rest-api/comment-page-1/#comment-4268 JakaJancar Wed, 04 Mar 2009 19:31:32 +0000 http://www.dimuthu.org/?p=408#comment-4268 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. 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.

]]>