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)? >
