Tip

WADL: The REST answer to WSDL

Web service developers were stirred a few months ago in the technical media over the SOAP vs.

    Requires Free Membership to View

REST debate, a now familiar theme which seems to come up every so often and one discussion which will surely never be completely settled given that each approach has its own technical merits on which to stand. But appropriate as each technique is for certain circumstances, until recently, there was one obvious part missing in RESTful approaches that was ever present in SOAP: the concept of a descriptor. Up next, we will explore an up and coming proposal named Web Application Description Language (WADL), which aims to provide descriptors for RESTful services.

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 java -jar 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

There are Comments. Add yours.

 
TIP: Want to include a code block in your comment? Use <pre> or <code> tags around the desired text. Ex: <code>insert code</code>

REGISTER or login:

Forgot Password?
By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy
Sort by: OldestNewest

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

Disclaimer: Our Tips Exchange is a forum for you to share technical advice and expertise with your peers and to learn from other enterprise IT professionals. TechTarget provides the infrastructure to facilitate this sharing of information. However, we cannot guarantee the accuracy or validity of the material submitted. You agree that your use of the Ask The Expert services and your reliance on any questions, answers, information or other materials received through this Web site is at your own risk.