Re: [CODE4LIB] REST interface types
On Tue, Jul 19, 2011 at 11:33 AM, Ralph LeVan ralphle...@gmail.com wrote: Where at all possible, I want a true REST interface. I recognize that sometimes you need to use POST to send data, but I've found it very helpful to be able to craft URLs that can be shared that contain a complete request. As a minor clarification: if all of the parameters are of types can be put in the URL, most form processing libraries used with most HTTP servers will take care of the difference between url and form encoded arguments, and make them available via the same API calls. It is not out of the question to encode all the parameters needed for some updates in the URL; however, if the operation is intended* to change state then the HTTP GET/HEAD/etc. methods should not be used, as described in the HTTP specifications (that's why web browsers have to ask if you want to repost a form when going back over a POST request, and why spiders should only use HEAD/GET type methods. Also, REST apis can include POST style updates (indeed, should not perform updates on GET requests over HTTP). Simon
Re: [CODE4LIB] REST interface types
On Jul 19, 2011, at 11:33 AM, Ralph LeVan wrote: Where at all possible, I want a true REST interface. I recognize that sometimes you need to use POST to send data, but I've found it very helpful to be able to craft URLs that can be shared that contain a complete request. But there's more than just the URL that's used in REST. As it uses HTTP, you could vary the response based on the Accept-Language or Accept headers. Some implementations use file extensions in place of Accept, but then you're assigning URIs to the container and not the contents. Am I trying to identify the data, or the data formatted as XML? Language is a bit messier, as it's the content, but when we're looking up something like in Dewey ... are we trying to identify the DDC 600s, or specifically the German labels for the 600s? Dewey.info packs it in the URL: http://dewey.info/class/6/2009/03/about.de But am I supposed to know that the english and french don't share the same root as the german? http://dewey.info/class/6/2009/08/about.en http://dewey.info/class/6/2009/08/about.fr Some groups will then put this in either as part of the QUERY_STRING or pass it in via PATH_INFO. -Joe
Re: [CODE4LIB] REST interface types
Actually, what I really wanted to know was whether or not the people here-subscribed would expect a proper REST interface to have an associated media type and to use hypertext as the engine of application state. In the link I originally provided [1], that's the final distinguishing characteristic of a REST interface. The discussion here seems to be about RPC-URI tunneling or HTTP-based Type I. But that's useful as well, since it indicates I'm probably over concerned with architectural style, and should just build something. Thanks, Devon [1] http://www.nordsc.com/ext/classification_of_http_based_apis.html On Wed, Jul 20, 2011 at 2:35 PM, Jonathan Rochkind rochk...@jhu.edu wrote: On 7/20/2011 1:04 PM, Joe Hourcle wrote: On Jul 19, 2011, at 11:33 AM, Ralph LeVan wrote: Where at all possible, I want a true REST interface. I recognize that sometimes you need to use POST to send data, but I've found it very helpful to be able to craft URLs that can be shared that contain a complete request. But there's more than just the URL that's used in REST. As it uses HTTP, you could vary the response based on the Accept-Language or Accept headers. While that is pure REST, I find it very difficult to debug, and also very difficult to then have a unified architecture for browsers as well as non-browser software clients -- since you cant' really control what accept headers a browser sends (and sometimes you DO want a non-HTML response to a browser -- download in EndNote format for instance), and most browsers can't send PUT/DELETE either. The best compromise seems to having equivalents for everything that can be expressed in a GET/POST with standard headers. For instance, the Rails framework will respect Accept headers for content-negotiation if sent, but you can ALSO use elements in the URL path instead: GET /foo with Accept header application/xml is equivalent to: GET /foo.xml And likewise, the Rails framework provides magic query params that let you express PUT/DELETE as a POST. (This isn't perfect, because PUT/DELETE _are_ supposed to be idempotent, whereas POST is not neccesarily. But PUT/DELETE are _not_ 'safe', and GET is 'safe', so it's not safe to use GET to represent a PUT/DELETE). PUT /foo is equivalent to POST /foo with key/value _method=PUT included in form-encoded body But even that kind of assumes that the body will be form-encoded, whereas with 'pure REST' it's often convenient to have it be something else (like XML), but then there's no clear way to send that _method=PUT. It gets complicated. But I think trying for pure REST just for the sake of purity ends up making things more complicated, including making your application code much more complicated, which serves nobody. Even this kind of modified pure REST but with simulation through GET/POST without relying on request headers, like Rails does, kind of requires a framework like Rails to do it for you to keep from getting out of hand. I think we just do the best we can, keep in mind the principles/goals of REST, rather than any particular picky rules, try to get as close to them as you can without having to make your application code become monstrous (and hard to understand for the developer/debugger). Jonathan -- Sent from my GMail account.
Re: [CODE4LIB] REST interface types
On 7/20/11 12:28 PM, Bill Janssen jans...@parc.com wrote: A couple of good rules-of-thumb to keep in mind: 1. URIs name objects; they do not name actions. So if you've got requests like GET /foo/getAuthors?doc=bar, you're doing it wrong. It should be something like GET /foo/doc/bar?field=authors, or even better, GET /foo/doc/bar/authors. I would also add that URLs like GET /foo/search?q=books are perfectly RESTful, as long as they are pointing to an algorithmic resource, like a search or some kind of calculation. Aaron
Re: [CODE4LIB] REST interface types
Where at all possible, I want a true REST interface. I recognize that sometimes you need to use POST to send data, but I've found it very helpful to be able to craft URLs that can be shared that contain a complete request. Ralph On Tue, Jul 19, 2011 at 11:22 AM, Devon dec...@gmail.com wrote: I'm getting ready to write a REST interface to OCLC's crosswalking system. My problem is that I'm not convinced developers actually want a textbook REST interface. I have a hunch that most developers really just want a non-SOAP url they can POST to with a crosswalked version returned in the response body. Given the classifications here [1], I was wondering if people could give some feedback about what interface type they'd actually want to use, what might be too much effort to use, and what they're sure they don't want. Thanks, Devon [1] http://www.nordsc.com/ext/classification_of_http_based_apis.html -- Devon Smith Consulting Software Engineer OCLC Research http://www.oclc.org/research/people/smith.htm
