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?
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? Regards, Ian. On Mon, Mar 24, 2008 at 10:00 AM, Rob Heittman <[EMAIL PROTECTED]> wrote: > > I'll let someone who uses JSON more than me answer about the idiom of the > JSON traversal, but it looks OK to me. If you are using the 1.1 Restlet > API, you want to override storeRepresentation() instead of put(). > > For my 2 cents, I don't think you need to explain the HTTP PUT operation. > Whatever implementation language and/or HTTP client library people are > using, they should have documentation and/or existing knowledge for that -- > and the means may vary *dramatically*. If there is a very likely use case > (JavaScript and XmlHttpRequest, etc.) you can document it in full. > Otherwise, maybe give some pointers to existing Web documentation ... > personally, I wouldn't reinvent the wheel in explaining how to make HTTP > calls -- or create JSON structured objects. That seems like a heavy > documentary load to lift. > > - R > > > > On 3/24/08, Ian Clarke <[EMAIL PROTECTED]> wrote: > > Hi Rob, > > > > Thanks for the feedback. I certainly agree that examples are often > > the best form of documentation. > > > > But, my particular concern was, how do I explain, in a language (and > > library) neutral way, how to send a JSON object to a resource via a > > HTTP PUT request. > > > > I'm also concerned to ensure that the method I'm using to interpret > > the PUT request (see code in my original email) is correct. > > > > Regards, > > > > Ian. > > > > On Mon, Mar 24, 2008 at 9:19 AM, Rob Heittman > > <[EMAIL PROTECTED]> wrote: > > > Hi Ian, > > > > > > At my outfit, when we've written elaborate REST API documentation, > evidence > > > indicates hardly anyone reads it :-) > > > > > > I've had the best results with documentation by example ... to start > with, > > > write out a few examples of the actual representation in likely use > cases, > > > and if time permits, give a couple examples of how to construct and send > it > > > in the most likely client languages (Javascript, Ruby, etc.). I think a > > > great use of time is ensuring that your Web service emits informative > and > > > helpful error messages in the response entity if something is malformed > or > > > unexpected. > > > > > > I think the majority of developers (especially in scripting and dynamic > > > languages) like to just whip something together and try it out. > > > > > > - R > > > > > > > > > > > > On Mon, Mar 24, 2008 at 10:04 AM, Ian Clarke <[EMAIL PROTECTED]> > wrote: > > > > > > > Can anyone give me some advice on how I should document this for > > > > client writers (who will probably be using languages other than Java)? > > > > > > > > > > > > > > > > > > -- > > Email: [EMAIL PROTECTED] > > Cell: +1 512 422 3588 > > Skype: sanity > > > > -- Email: [EMAIL PROTECTED] Cell: +1 512 422 3588 Skype: sanity
