On Dec 7, 2006, at 7:10 PM, Steve Jones wrote: > How do I document and formalise to a consumer how they get an invoice > or place and order? What format do I use to describe the URI, > Request, Response, pre-conditions, post-conditions and invariants of > the invocation? How is this description then versioned, published and > managed. >
The best answer probably is: You use a collection of HTML pages. Very few things are formalized, e.g. documentation of namespaces with RDDL, but that's orthogonal to REST and HTTP. Another spec currently being created is URI templates (http:// bitworking.org/news/URI_Templates), which might become part of a larger description language. It's (obviously) not yet widely deployed, . There's an ongoing discussion about description languages for the Web at [EMAIL PROTECTED], archived at http://lists.w3.org/ Archives/Public/public-web-http-desc/. One candidate is WADL (Web Application Description Language), documented at http:// wadl.dev.java.net/. > > Saying REST is simple means that this should be simple.... An HTML page *is* simple, probably no doubt about that. Wether it's sufficient is another (very valid) question. A typical REST answer (and one that I don't fully agree with) is that you're no better off in WS-* land; you can use XML Schema in REST, too, WSDL doesn't add very much (and definitely not enough) on top, and the fixed interface means you have a reduced need to document things. As I said, I don't really buy into this line of reasoning. Stefan -- Stefan Tilkov, http://www.innoq.com/blog/st/
