On Mon, Mar 24, 2008 at 11:07 AM, Ian Clarke <[EMAIL PROTECTED]> wrote:
> I'm using Restlet 1.0.8 - would you recommend using 1.1? How stable > is it relative to 1.0.8 - and what are the benefits? The usual caveats apply. 1.1 isn't an official production release. The Restlet project tends to emerge VERY stable milestone releases, however, and my company does use them in production quite often. I prefer 1.1M2 for a number of reasons, both new features and API changes included. Here's the changelog: http://www.restlet.org/documentation/1.1/changes Does the use of methods like getRepresentation() and > storeRepresentation() not cause a problem because they decouple > Restlet from the underlying HTTP protocol terminology? > Specifically, if I say to a client writer that isn't using Restlet > that they should "store a representation" in a URL, it is less likely > that they will know what do to relative to saying that they should > "PUT" it (this being the name of the HTTP method they should use). > > Probably not the best example, but generally, wouldn't it be better to > stick with terminology that will be familiar to people who are only > going on the HTTP spec? > > Or perhaps we are assuming a familiarity with REST terminology, rather > than HTTP terminology alone? > REST and Restlet terminology *is*, by and large, HTTP terminology. The word "representation," for example, appears in the very first paragraph of the abstract of the HTTP/1.1 specification, with the exact meaning used here in Restlet. I think you have hit on a significant issue, though -- that very few implementers actually have read the HTTP specification *per se*, nor studied the architectural style in an abstract way, and words like "entity" and "representation" seem alien to them. They do recognize words that manifest in a well-known or well-used implementation. So they recognize "method" and GET and POST because they appear in the ubiquitous <FORM> tag. Java developers recognize "request" and "response" from the Servlet API. On balance though, if they've never seen the word in an implementation, and it applies to one of the more abstract concepts of HTTP or REST architecture, I think the odds are excellent that this will be unfamiliar. Conversely, they best understand words that, while not strictly REST words, appear consistently in their frame of reference. Given this, based on your assessment of the preferred technologies and level of sophistication of your client implementers, I would document in words they understand. Orson Scott Card: "I speak to everyone in the language they understand ... That isn't being slick, it's being clear."* * I just read an API doc where the documenter said: "POST the following variables to the following action" That's not particularly eruditely stated, but it's simple, clear, and surely gets the message across to the average Web developer. There's no blather about constructing a form representation with x-www-url-encoded encoding, and the HTML word "action" is used where I'd have said "URI", but still the message gets across pretty clearly ...* *- R
