To define and describe a web-service API, many developers would use WSDL. Although WSDL is meant to be extensible to any protocol and message format, most people use it for HTTP GET/POST and SOAP, when writing to WS-* standards. On the other hand, developers writing a REST API using XML over HTTP typically don't use WSDL, or any other standardized definition/description of the API. There will usually be some kind of human-readable documentation, but that's as far as it goes.
Not everyone is convinced that we need to describe and define REST-ful APIs, but there are those who believe it's useful. Tim Bray suggests that it's what we need to allow users to consume an XML/HTTP API in a few lines of code. It's certainly true that machine-readable descriptions of web APIs can allow the generation of a language-specific library.
For those who would like to describe their XML over HTTP service, a lot of options have been discussed, from SMEX-D (proposed by Tim Bray) to NSDL, and a host of alternatives. However, most of those proposals were made in 2005 or earlier, and since then none has really seen much adoption.
Marc Hadley (one of the Spec Leads for JSR-311, a Java API for RESTful services) back in 2005 proposed WADL, the Web Application Description Language.
Since then, a number of people have been building tools to support WADL. Yahoo architect Mark Nottingham is maintaining a stylesheet to generate documentation from WADL.
Last week, Google's Thomas Steiner unveiled that he is working on a Google project for generating language specific client libraries from WADL and generating WADL from documentation examples, tentatively called Google REST Compile and Google REST Describe. Thomas chose WADL as the description language to be used with the new tool, after examining all the alternatives
The Sun Developer Web Pack was also released last week and contains prebuilt binaries of some WADL tools developed by Marc Hadley.
With architects at Yahoo, Google, and Sun choosing WADL for their REST tooling, perhaps WADL will receive more adoption. For more information on WADL, the reasons behind it and the alternatives, Marc Hadly's presentation (PDF, Google's HTML translation) is a good overview.
Not everyone is convinced that we need to describe and define REST-ful APIs, but there are those who believe it's useful. Tim Bray suggests that it's what we need to allow users to consume an XML/HTTP API in a few lines of code. It's certainly true that machine-readable descriptions of web APIs can allow the generation of a language-specific library. For those who would like to describe their XML over HTTP service, a lot of options have been discussed, from SMEX-D (proposed by Tim Bray) to NSDL, and a host of alternatives. However, most of those proposals were made in 2005 or earlier, and since then none has really seen much adoption.
Marc Hadley (one of the Spec Leads for JSR-311, a Java API for RESTful services) back in 2005 proposed WADL, the Web Application Description Language.
Since then, a number of people have been building tools to support WADL. Yahoo architect Mark Nottingham is maintaining a stylesheet to generate documentation from WADL.
Last week, Google's Thomas Steiner unveiled that he is working on a Google project for generating language specific client libraries from WADL and generating WADL from documentation examples, tentatively called Google REST Compile and Google REST Describe. Thomas chose WADL as the description language to be used with the new tool, after examining all the alternatives
The Sun Developer Web Pack was also released last week and contains prebuilt binaries of some WADL tools developed by Marc Hadley.
With architects at Yahoo, Google, and Sun choosing WADL for their REST tooling, perhaps WADL will receive more adoption. For more information on WADL, the reasons behind it and the alternatives, Marc Hadly's presentation (PDF, Google's HTML translation) is a good overview.