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
