WADL REST API description language getting some attention

by Geoffrey Wiseman on Mar 19, 2007 |

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.

Related Editorial

The Rise of the Composite API Platform, a ‘Best-of-Breed’ API Management Solution

A Unified Mobile Architecture for the Modern Data Center

Enterprise-class API Patterns for Cloud & Mobile

451 Group Analyst Report: Review of Intel & Mashery API Management Platform

API Management - Application Security Made Easy

Related Sponsor

*Cloud API Management – the Service Gateway Approach
*451 Group Analyst Report: Review of Intel & Mashery API Management Platform

Hello stranger!

You need to Register an InfoQ account or to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Community comments

WSDL by Nikolai Ivanov Posted

I would stay with WSDL by Frank Thompson Posted

Re: WADL usage and associated benefits by Don Holloway Posted

implemention of WADL by Jon chritz Posted

WADL to describe interaction, not services. by William Martinez Posted

WSDL by Nikolai Ivanov

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

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.

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

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.

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/

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