Much has been written concerning the potential need for a description language for REST based web services. Much of the writing has assumed that REST does not have a defined description language.  Much of the discussion has revolved around REST’s proponents assertions that the request query parameters are the themselves the description.  Some have also noted WADL as a possible solution.

The Form

I do aver that REST already has a full web service description language built into it in the HTML Form.  In the most normal of cases, that of human web browsing itself, the HTML Form is already used in a manner declaring the exact parameters to be passed and matching the parameter to its user defined, dynamic value.  The HTML Form provides a standardized format to the definition of what query parameters are required for a given service.  For though the query parameters may be said to be self descriptive, without an HTML Form, a user or client will have no prior insight into the full set of parameters required or optional to invoke the service.  The HTML Form as RESTful service descriptor adheres to the text of the Fielding definition itself, where hyperlinks provide the “engine of application state.”  The HTML Form action parameter provides the hyperlink required to direct the transfer of state from the client to the service.

As for the common desire to automatically generating a service from a given HTML Form, taken as a web service description, we should look no further than the myriad of CGI languages and frameworks available, from Perl to C to Java to .NET to Struts and more, all of which provide to the developer a simple key/value pair for everything passed in the request.

Why don’t I see WADL as a solution?  Because it assumes that the typical SOAP implementation of code/class generation and the corresponding marshalling and unmarshalling is what is wanted or needed.  I would assert that the reason that the number of RESTful web services implementations is growing and the reason that the web itself has been so successful is that RESTful services (or web pages themselves) are very simple and very scalable.  Simple in a way that WSDL, WADL, or any other heavy description language will never be.  Scalable by default in a way for which SOAP implementations must intentionally strive.

What about XML payloads then?  Well, you could of course declare an XML type for a parameter in an HTML Form, but that would not really meet the expectations of those that are now developing serious SOAP based services, desiring a strongly typed description language.  The solution as it turns out is the successor to the HTML Form, XForms. XForms provides a full MVC approach to web application or web service description.  An XForm can be represented as a simple HTML Form, or may take on much more complex capabilities, such as defining specific XML parameter types and sending XML directly to the server.  In this manner, XForms may be transformed to provide a human readable interface to a service, or may also be read by a machine in raw XML form to determine proper parameters and service location.

Concerning REST service descriptions:

• Debate: Does REST Need a Description Language?
  
• REST Service Description Conventions (RSDC)
• A discussion of the use of WSDL 2.0 to describe REST web services
• Describe REST Web services with WSDL 2.0
• Does REST need a service description language? – [asserts that a WSDL like language is not needed for REST]
• WADL REST API description language getting some attention

Concerning XForms:

• W3C Forms Working Group
• XForms FAQ
• XForms Essentials
• XForms Tutorial
• Understanding XForms: The Model — Particularly applicable to this conversation.

Also interesting:.

• XForms as part of the XRX Application Architecture [Forms on the client, REST interfaces and XQuery on the server]