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 >
