Is It Time For WADL in JAX-RS?

| by Mark Little Follow 15 Followers on Oct 14, 2012. Estimated reading time: 4 minutes |

At this years JavaOne there was a session titled 'JavaEE.Next(): Java EE 7, 8, and Beyond' at which the panel, including Oracle, IBM, Red Hat and Caucho, discussed various aspects of Java EE and answered questions from the audience. However, despite the fact that the focus was intended to be on things such as PaaS, mobile and NoSQL, there was a lot of interest on REST and particularly around WADL. Now WADL isn't new, having been around and discussed fairly widely for at least 7 years and as we reported in 2005:

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.

As with a few other things around REST, in the past WADL appeared to fracture the community into those who believe it's necessary and those who don't. For instance, back in 2007 Mark Baker had this to say:

[...] all services expose the same interface. This is what provides the majority of its loose coupling, and is the principle differentiator from RPC. 

So if you’re writing (or generating) contract/interface-level code which can’t late-bind to all resources, everywhere, you’re not doing REST (10 kudos to whomever identifies the specific constraint being violated).

Cut the cord already! RPC is dead. You’re not in Kansas anymore.

And those who like it often compare it with WSDL:

Remember about WSDL, where you can simply generate this interfacing code to the web services? That was pretty nifty. That saved a lot of work. Can’t we do the same with RESTful web services? Well, yes, you can. And yes, finally I’m coming to my point. You can do this with WADL. WADL stands for Web Application Description Language. It allows you to describe essentially any HTTP-based API to any web service Including SOAP webservices, if you would feel so inclined. But you can also describe the flickr API, the twitter API and the yahoo API in WADL. And guess what it can do… It can generate client-side proxy code to interface with these Web APIs. Yes, it’s like WSDL, but more general. Generalized to also support REST and basically any kind of (I guess) XML-based web service.

But this can be a double-edged sword as one of the commenters pointed out:

You've made a few fundamental mistakes in this article. You said "What I refer to here is that the format of results and data you send to a
REST webservice is not more precisely defined than “dude, it’s XML!”". Then what may I ask are media types? They are precisely definitions of message formats, associated with information on how to process the data and access new resources based on links present in the representation.

Read up on some of Roy Fielding's work ; )

Oh and by the way, WADL is probably not going to last long, and is actually not very RESTful at all (creates tighter coupling between client and service provider).

For a few years between 2005 and 2008 this debate raged along with many others in the REST arena. In recent times it appears to have died down and a more pragmatic outlook has taken hold, with some groups deciding that despite any perceived issues with WADL (e.g., whether or not it is RESTful) it should be a supported option for developers, and other groups eschewing it completely. For instance, Jersey the JAX-RS reference implementation supports WADL out of the box. But some other JAX-RS implementations, such as RESTeasy, are not so definitive.

Which leads us back to the JavaOne session, where several people in the audience, including the JAX-RS specification lead, were keen to learn whether or not WADL should be a fully supported aspect of a future version of JAX-RS. Whilst the panel were non-committal, referring to the plethora of RESTful services that have been implemented successfully without WADL, many in the audience appeared to be supportive of adding WADL to JAX-RS. Since the emphasis on WADL over the past few years has been relatively low-key, is this specifically a Java and JAX-RS requirement or is WADL on the rise again? And if so, is WADL any better today in terms of RESTful services and applications than it was several years ago or are developers just more pragamtic today than they were back then?

Rate this Article

Adoption Stage

Hello stranger!

You need to Register an InfoQ account or or login 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

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Why wouldn't we just adopt Swagger? by Dave McCrory

Swagger is OSS, generates clients in multiple languages (Java, Scala, Ruby, etc.) and uses JSON instead on nasty XML. So why would I consider WADL for even a second?

OData is heading to OASIS for standardization; so OData instead of WADL by Faisal Waris

It seems that OData has much better traction than WADL. The OASIS submission has the backing of Microsoft (where it originated), IBM and SAP.

OData specs are (or at least appear to be) more thorough:

The REST model of 'no contracts' has not panned out so no one is doing 'proper' REST anyway.

As an aside...

Longer term, I can see AMQP as a viable alternative to HTTP for many mobile rich client applications (HTTP only works well under persistent and pervasive connectivity). Adoption of AMQP will move us away from a web model to a more messaging oriented model.

No please, not again... by Jan Algermissen

WADL has no place in RESTful architectures. It never did and it doesn't now. And there is definitely no need to confuse people by raising the subject yet again.

As you quote:

"Cut the cord already! RPC is dead;"

If in doubt, read (and understand):

WADL is fine as a server side, developer tool. E.g. for test generation. But the minute you let it out of the door, you get exactly the kind of RPC coupling that you aim to avoid by using REST.

The right way to do it is



Re: Why wouldn't we just adopt Swagger? by Raymond Feng

+1 on swagger too. I love it.

Re: OData is heading to OASIS for standardization; so OData instead of WADL by Jan Algermissen

Faisal, you assert that "HTTP only works well under persistent and pervasive connectivity". Can you explain what you mean by that?

An can you explain how a message oriented model would look for, e.g. an ecommerce site and a million of concurrent mobile clients? Where is the benefit over HTTP?

As it stands I find your assertion a rather bold, unbacked statement.


Re: OData is heading to OASIS for standardization; so OData instead of WADL by Faisal Waris


The rich mobile clients that I am talking about are 'apps' (as opposed to mobile web). Note that Windows 8 (desktop/tablet) is the newest platform to support apps (in addition to Android, IOS and Windows Phone).

Many apps need to work in the background; handle offline storage and processing; and deal with intermittent connectivity. For such applications a message oriented protocol is more natural (which may be combined with http for synchronous needs).

I understand that HTTP/HTML is being 'barnacled upon' with duplex communication (web sockets) and offline storage but they were not originally designed for such needs. App developers will need to do more work to support such features in their apps, both from client and server points of view.

For asynchronous communication over intermittent connections AMQP looks a lot better because the programming burden should be much lower, for both ends. You can do the same with HTTP/HTML (or even plain sockets) but with more work and less interoperability.

I don't see any scalability issues with AMQP. It supports COMET style 'long-polling' connections. Moreover, all app platforms have some kind of push-notification systems that may be combined with AMQP. (As an experiment, I built a push-notification system using WCF Duplex Binding and asynchronous IO to support 33K concurrent connections to a single machine. See: There is nothing in the AMQP protocol that would preclude millions of concurrent clients.

I am not currently an AMQP expert but it does seem to support true transactions. Also you can combine AMQP with SOAP (which is protocol agnostic) for highly secure messaging using WS-Security (XML based signing and encryption).


Re: OData is heading to OASIS for standardization; so OData instead of WADL by Jan Algermissen


sorry, can't let that assertion just stand there:

"Many apps need to work in the background; handle offline storage and processing; and deal with intermittent connectivity. For such applications a message oriented protocol is more natural"

How so? Why would HTTP (normal request/response) be less natural for such apps?

Especially in the case of unstable connection, an architectural style that keeps application state on the client is much more suitable because a client can at any time simply continue from where it was in the application.

In your first reply you also said:

"The REST model of 'no contracts' has not panned out so no one is doing 'proper' REST anyway."

What do you mean by "The REST model of 'no contracts'"?

And your observation "no one is doing 'proper' REST anyway" is based on which data?

Or is that merely an *assumption* of yours?


Re: OData is heading to OASIS for standardization; so OData instead of WADL by Faisal Waris

A. Let’s first take REST and contracts. My understanding is that a 'proper' REST client makes no a priori assumptions about what it's going to receive say after it issues a GET request. The client is supposed to inspect the response at a very high level (media-type or document root) and generically handle the contents. By "generically handle" I mean extract and present the information and links (hypermedia) to a human or a software agent to make decisions and drive the application state (late binding). Responses cannot be application specific.

I have never seen this being done in actual practice. All of the so-called 'REST' services I have encountered are APIs, i.e. the client has an expectation of what it’s going to receive as result of a GET request (early binding). There is always a (specific) contract which may be implicit (i.e. not described via metadata) but it’s nonetheless there.

My understanding of REST and contracts is from reading commentary by Fielding himself (note I have only skimmed through his thesis).

B. REST is based on the client-server application model. A software agent or human is in control and is actively making the decisions. There is no notion of events or asynchronous messages. Let’s say that a mobile client subscribes to a stock service and is notified each time a stock’s price changes by 5%. REST (that I know of) does not handle such cases. A more complex scenario is that you are only interested in a higher level event based on several lower level events. For example, I am in a specific location or neighborhood and two of my friends happen to be near at the same time.

A Contract is a Contract by Saul Caganoff

While I understand the issues around contract based development and the coupling that results. The fundamental issue is that a contract is always required...regardless of how restful your service is. Using any restful service requires a knowledge of the URI structure (resource names and hierarchy) as well as how to interpret the associated json or (gasp) xml structure encountered with any GET, POST or PUT methods. And I don't just mean parsing the json/xml - anyone can do that because both are self-describing - I mean the semantic interpretation of the resource structures. Ultimately I need to be able to map those structures into my client application which means I need a semantic description of each resource structure.

The current standard for this seems to be human readable HTML+CSS - in other words RTFM. The HTML is the contract just as much as any WADL or WSDL or Swagger description might be. The main difference is that some formats are machine readable while others are not.

Machine readable has its own issues as we discovered with the many and varied problems in binding SOAP encoding to various languages and I understand if practitioners are reticent to head down that path in the rest world. But relying on an HTML description (often with just examples as opposed to schema definitions) to be interpreted by developers with various skill levels seems somewhat old-fashioned and inefficient.

A contract is a contract. Consumers of restful services require a description of the resource hierarchy, structure and semantics. Other specifications such as security mechanisms, charging, availability etc are also useful. All these elements make up a contract between the service provider and consumer. Eschewing a formal service description doesn't really make this relationship any less of a contract or obligation.

Re: OData is heading to OASIS for standardization; so OData instead of WADL by Jan Algermissen


A. REST does have contracts, the difference to RPC from that POV is that the interface is uniform and the contracts are centralized (not server owned). HTML or AtomPub are quite a mouthful of contract and it is well possible to implement clients for them (aka Browsers, feed readers). There is no contact-less magic in REST.

There might not be many public RESTful APIs, but that does not mean it is not happening. I personally see 'proper REST' picking up speed behind the firewall for sure. And many not-quite-RESTful public APIs just lack a media type spec or two to fix them.

B. If you have a use case that cant be solved with polling and really requires push (most use cases don't, BTW) then an event based architectural style is the proper thing to use. It would be insane to suggest otherwise.

However, there is a huge difference between that statement and the one you made in your initial reply where you implied that message based style would be superior to HTTP for mobile clients. That's just a catchy thing to state, not an architecturally sound assertion.


Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

10 Discuss