Questions on proper REST design

views:

133

answers:

+1 Q:

Questions on proper REST design

I'm designing a REST web-service and have questions on best/proper design.

A search method should be POST, since identical requests don't have to return the same data, right? Also, is it better to do /search/term or /search and have term as post-var?

Also, what if a resource can be updated at any time, would the method to return it be a GET or a POST. It sounds best to be a GET, but since it can change over time, it isn't idempotent.

+1 A:

Since you're not modifying the resource, I would recommend using a GET with the search term in the URL. Cache expiration on the page should be set appropriately (as with all other resources). In this case, you might even want to disable caching entirely.

EvilRyry 2009-09-13 16:37:49

Continuing what I said to William Pietri above, I guess that could work for the search method with just the cache disabled.In theory I could disable cache on other resources, since they can be updated at anytime and have the method to get them be a GET?

jimktrains 2009-09-13 16:51:12

+3 A:

Idempotence means that your request doesn't change your resource, not that the resource never changes.

Search requests should always be GETs. This is especially important in the browser use case, because search requests should be bookmarkable, linkable, and forwardable.

A good example is Google:

http://www.google.com/search?q=rest+architecture

William Pietri 2009-09-13 16:38:30

Doesn't http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html define idempotent as "Methods can also have the property of "idempotence" in that (aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request. The methods GET, HEAD, PUT and DELETE share this property."That's what confused me, otherwise I would have done it as a GET for the reasons you said. This is also for an API, so it doesn't have to be bookmarkable, which is why I was wondering if the search term should be a post var, and not part of the url.

jimktrains 2009-09-13 16:49:15

I don't think it is reasonable to say searches should always be GETs. There may be scenarios where POST is a better option. There in nothing in REST or HTTP that says a POST cannot do a search.e.g. Imagine if the search was going to take several hours, you might POST a search request which would return a location of the current search status. When the search is complete the status could contain a link to the results.

Darrel Miller 2009-09-13 19:15:55

jimktrains: Yeah, that's a much better definition than my lazy one above. I conflated idempotence, where multiple identical requests cause no more change than one, and the right behavior for GETs, which don't cause any server-side change at all.Note that for RESTful APIs, a person with a browser *is* a valid client. So is your app. And either one might want to hold on to a search URL if they want to repeat the same search later.

William Pietri 2009-09-14 02:55:42

Darrel Miller: That's true, and a reasonable architectural pattern for long-lived requests. On the other hand, in that case you could still do the search as a GET, and just give a response that indicates the search isn't done cooking yet. I'd only go with the more complicated approach if I wanted to treat the search request as a first-class resource. E.g., being able to cancel it with a DELETE call, or modify the running request with a PUT.

William Pietri 2009-09-14 03:02:36

I recommend a GET with /search/term To update POST To create a new something PUT

Shaun 2009-09-13 16:40:18

You cannot directly correlate POST to update and create to PUT. PUT can update and create, POST could create, update or do neither. The behaviour of POST is not defined by the HTTP spec, there are simply suggestions of it is commonly used for what it could be used for.

Darrel Miller 2009-09-13 19:18:12

ansaurus

tags:

views:

answers:

Questions on proper REST design

related questions