Web service developers were stirred a few months ago in the technical media over the SOAP vs.
For SOAP Web services, descriptors based on Web Services Description Language (WSDL) form a fundamental piece of their actual design, mainly on account of the underlying complexity present in the actual service. In these scenarios, a descriptor not only serves the purpose of formally describing all the business logic it can fulfill, but it also aides in the creation of helper classes -- often called stubs -- used to build service clients.
Enter WADL, a similar description language to WSDL, but strictly targeting the requirements of RESTful services. REST started of simple enough, as live URL's on major portals which returned structured data to querying clients, but as interest has grown in this alternate approach to Web services, so has the scope and size of the business processes it attempts to fulfill, making descriptors a natural addition.
REST services being based on the back of HTTP can have the same methods -- GET, POST, PUT, DELETE, HEAD -- available in this latter protocol. Input parameters on the other hand can also grow to be numerous for complex services, making the use of required, optional and type values a welcomed guide for developers trying to make sense of first time requests. When it comes to response values, structure responses have also grown in complexity, ranging from custom XML namespaces to JSON, no to mention the handling of fault scenarios in case a request is aborted.
With that said, lets take a look at a WADL descriptor.
Listing 1.1 WADL descriptor
<?xml version="1.0"?> <application xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:yn="urn:yahoo:yn" xmlns:ya="urn:yahoo:api" xmlns="http://research.sun.com/wadl"> <grammars> <include href="NewsSearchResponse.xsd"/> <include href="NewsSearchError.xsd"/> </grammars> <resources base="http://api.search.yahoo.com/NewsSearchService/V1/"> <resource uri="newsSearch"> <method href="#search"/> </resource> </resources> <method name="GET" id="search"> <request> <query_variable name="appid" type="xsd:string" required="true"/> <query_variable name="query" type="xsd:string" required="true"/> <query_variable name="type" type="xsd:string"/> <query_variable name="results" type="xsd:int"/> <query_variable name="start" type="xsd:int"/> <query_variable name="sort" type="xsd:string"/> <query_variable name="language" type="xsd:string"/> </request> <response> <representation mediaType="application/xml" element="yn:ResultSet"/> <fault id="SearchError" status="400" mediaType="application/xml" element="ya:Error"/> </response> </method> </application>
As you can see, a WADL contract is pretty self descriptive by itself, but there are of course more things you can do with it. One of the most notable actions to take though, is to create stub classes from these WADL contracts to ease the creation of service clients -- an identical process to that of SOAP-based WSDL contracts.
In order to create such service client stubs, an early WADL implementation provided by Sun is
equipped with a
wadl2java tool, which as its name indicates, takes a WADL contract and
creates its corresponding Java stub classes. Executing the following instructions
wadl2java.jar -o gen-src -p com.techtarget.rest http://www.techtarget.com/newsrest.wadl on
the previous WADL contract would generate its corresponding Java stubs.
While the mechanics of using such an approach -- that of automated code generation -- have caused criticism among early WADL analysts, stating that its not only unnecessary, but that it will start REST down the same path as SOAP and other distributed technologies like CORBA, which depend on intermediate languages/descriptors, from a practical point of view one cannot deny that using such a contract to obtain stub classes is an even quicker way to get started with REST-based Web services clients.
While WADL is still in its early phases and tools are currently available only for Java environments -- contrary to WSDL, which is more ubiquitous -- WADL's appearance is a vote of confidence in favor of the REST approach to building Web services and will in all likelihood become a tight knit companion when undertaking REST designs in the enterprise, just like WSDL has been one for SOAP.
About the Author
Daniel Rubio is a software consultant with over 10 years of experience in enterprise software development, having recently founded Mashup Soft, a startup specializing in the use Web services for Mashups. He is a technology enthusiast in all areas related to software platforms and maintains a blog on these topics.
This was first published in July 2007