Hi Ian, I believe you should override Resource.storeRepresentation() and override Resource.allowPut() -> true instead of overriding Resource.put()
As for your documentation concerns, I would explain that sending JSON is no different than sending any other text-based request entity. You should probably point them to a more general document on how to build JSON strings. Two pieces of advice on opening up to third-party clients. First, some languages (or their associated libraries) other than Java have poor or non-existent support for the HTTP PUT method. Just be aware of this when recommending implementation languages. Second, while JSON is slightly easier to work with programmatically, a lot of languages don't have native support for it. Depending on who your clients are, they might balk at having to download and install a third party library to access your service. XML might work out better because most languages have native support for it. Kevin On Mon, Mar 24, 2008 at 10:43 AM, 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 >
