WADL REST API description language getting some attention

Posted by Geoffrey Wiseman on Mar 19, 2007

Sections

Architecture & Design,

Enterprise Architecture

Topics

Web Services ,

REST ,

SOA

Tags

WADL ,

WSDL

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. 

1. Back to top

   WSDL

   by Nikolai Ivanov

   Many companies use XML and HTTP with no WSDL. Why bother? Thanks. www.1qcc.com

   Reply

2. Back to top

   I would stay with WSDL

   by Frank Thompson

   I understand the benefits of defining a standard, but it does not always mean that a standard will become widely adopted, instead, some de-facto standards can be very popular and widely accepted and implemented, for example, TCP/IP. Our goji berries website uses XML over HTTP without WSDL, as it is simple to declare the services, and is simple for users to call the services.

   Reply

3. Back to top

   Re: WADL usage and associated benefits

   by Don Holloway

   Andrew, thanks for the quick note. I've been working on a project to add some more utility to the concert and festival listings at www.websortings.com. Basic webpage listings for festivals aren't very good by themselves without date and location data for the actual event.
   
   I had done some research, and found some graduate research ils.unc.edu/MSpapers/2830.pdf done by Michael Graves at the University of North Carolina. He did a good job of defining the data schema, etc. But was recommending using RDF/XML. He recommended an ontology called OWL to define the event. I was fine with the data, sources, etc. but kind of got confused at the OWL layer.
   
   I do want the concert and event data to be available and accessible to outside applications, so it looks like WADL will provide a much simpler way to make sure that the data is structured properly. I read through the Sun power point presentation and it seems pretty straightforward. If it continues to be supported by Google, Sun, et all, it should be a pretty safe choice.
   
   Don

   Reply

4. Back to top

   implemention of WADL

   by Jon chritz

   Our small firm tried to implement it by ourself with no success. we had to hire and outside consultant. We want more hand on manual and sample project outline.

   Reply

5. Back to top

   implemention of WADL

   by Jon chritz

   Our small firm tried to implement it by ourself with no success. we had to hire and outside consultant. We want more hand on manual and sample project outline.
   
   www.haitianite.com/main/

   Reply

6. Back to top

   WADL to describe interaction, not services.

   by William Martinez

   I wrote a couple of blogs(A RESTFull WSDL?,WADL, REST and WSDL,WSDL 2.0 - a REST Friendly Language) about the need of a service message description for REST. One solution is actually WSDL, and WSDL 2.0 may even fit better. There I explain that WADL, to me, it not a clear way to describe a service, but it is more a detailed way to describe interaction. The level is lower than describing a web service, and thus closer to implementation than to contract description.
   
   Following this, WSDL is not replaced by WADL, but may be complemented by it. A WSDL may define the service, and a WADL generated from it to actually describe a REST implementation of the web service.
   
   William Martinez

   Reply

• Older >