On 07/12/06, Stefan Tilkov <[EMAIL PROTECTED]> wrote: > > > > > > > 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.
Which isn't as much use as a nice and formal WSDL which can be quickly consumed by standard tools. REST really needs to address this issue as versioning documents (which is what HTML is) is a step back over a formal and technical interface spec IMO. > > 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/. I'll check out WADL, for me this lack of a standard mechanism is a big mark down for REST as an enterprise solution so I'm assuming something will be sorted in the next 12 months. > > > > > 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. Nope me neither :) > > Stefan > -- > Stefan Tilkov, http://www.innoq.com/blog/st/ > >
