82

To describe RESTful we can say that every resource has its own URI. Using HTTP GET, POST, PUT and DELETE, we can operate on these resources. All resources are representational. Whoever wants to use our resources can do so via a browser or REST client.

That's the main idea of a RESTful architecture. This architecture allows services on the internet. So why does this architecture need WADL? What does WADL offer that standard HTTP does not? Why does WADL need to exist?

1
  • From Wikipedia: The Web Application Description Language (WADL) is a machine-readable XML description of HTTP-based web services.
    – Ricardo
    Jun 29, 2018 at 1:41

8 Answers 8

159

The purpose of WADL is to define a contract. Contract specifies how one party can call another.

When you create a web application from scratch, you don't need contract and WADL.

When you integrate your system with the other system and you can communicate clearly with their development team, you don't need contract and WADL (because you can make a phone call to make things clear).

However when you integrate a complex enterprise system with several others complex enterprise systems maintained by several different companies (or federal institutions), then believe me you want to have a communication contract defined as strictly as possible. Then you need WADL or Open Specification. Need it badly.

People with weak enterprise background tend to see entire IT as a collection of separated web applications developed independently. But enterprise reality is sometimes tough. Sometimes you can't even call or write to the people developing the application you have to integrate with. Sometimes you communicate with a legacy application that is no longer maintained--it just runs and you need to figure out how to communicate with it properly. In such conditions you need a contract because it saves your ass.

Actually client generation is the minor feature of the contract definition. It's just a toy. Contract enforces bad communicators to communicate integration rules clearly. This is the main reason to use WADL or Open Specification or whatever.

4
  • 8
    "--- IT SAVES ASS" was the best part. Is there any PHP code generator available from WADL file? May 20, 2015 at 10:46
  • If you don't need a wadl in a webapp. What do you have to do to send request to retrieve the values?
    – JayC
    Jan 25, 2017 at 14:32
  • You can ask the other team to provide you client SDK for example. Feb 1, 2017 at 13:46
  • How to use & integrate a web-/REST API (WA) with insufficient documentation? You 1-sentenced the benefit of formal WADL (alike WSDL): Contract enforces bad communicators to communicate integration rules clearly.
    – hc_dev
    Dec 13, 2020 at 12:04
37

Using WADL implies that you just might be gracious enough to actually define the data / documents you are passing back and forth. Say you are passing some XML fragments, they might actually be part of a defined schema.

Whether or not you use the DL to generate code is not very important to me. What matters, in my subjective opinion, is that it is important to have a formal agreement on interfaces between business partners. Even if what is passed is obvious, it helps to identify who has to fix what later if somebody changes the previous interface.

Data format is just as much a part of an interface as verb names.

2
  • 10
    Using REST requires that you define the data / documents you are passing back and forth. The problem with WADL is that it also tries to define the end-points which should not be part of the API definition. Aug 24, 2009 at 17:13
  • 4
    Derrel, I don't know of a single web service I have ever written a client for, that didn't have a single endpoint that it was used with. Oct 26, 2011 at 21:19
31

WADL appeals to people coming from the SOAP world where it is common to use a code generator to create client side code based on the WSDL. I don't think that mechanism is useful in REST as it creates client code that is coupled to server endpoints.

I believe that if you properly define your media-types and use hypermedia within those media-types, then it is not necessary to have WADL. The description of the available end-points is contained within the media-type definitions themselves. And if you are now saying to yourself, but application/xml doesn't contain any information about available hyperlinks, then I say BINGO. That's why I don't think application/xml and application/json are appropriate media-types for REST. I'm not saying don't use XML or JSON, just don't use the generic media type name.

The other appeal of WADL is for the purpose of documenting REST services. Unfortunately, it leads developers down the wrong path as WADL attempts to document server-side end points. Documenting a REST services should focus primarily on the media-types. A client developer should be able to write a REST client without knowing any url other than the root url.

11
  • 20
    WADL also appeals to those who have a boss who says you have to have a formal definition in a standard format. I'm not saying it's the best way to do that, just that some times it's useful to "check an organizational box", so to speak. That fact that it's overkill can be lost upon one's boss. However, having the formal def file can save you from being shoved back to the SOAP crack pipe that all the other cool corporate kids are sucking on.
    – Roboprog
    Aug 26, 2009 at 12:27
  • 2
    @Roboprog Document your media types instead of the end points. There are plenty of good examples at the IANA registry. Also, the Sun Cloud API is a good example. You have to convince your boss that documenting the endpoints is a bad idea for the future. Aug 26, 2009 at 14:07
  • 1
    It's also handy for developers who actually have more to do that write client code all day. Oct 26, 2011 at 21:16
  • 1
    @cboettig Schema is just a set of syntax rules, they add no semantics. You need some other mechanism like a media type or a profile to add semantics. May 22, 2013 at 23:19
  • 1
    @cboettig People do associate semantics to namespaced elements and attributes, but there is no standardized process for doing so. Media types have an official registry that points to specifications that define semantics. iana.org/assignments/media-types/application May 23, 2013 at 12:23
16

WADL allows you to generate code, tests and documentation. Actually there are few very useful tools utilizing WADL, you can see some examples here. The problem with the "pure" REST, as described in Fielding's dissertation, is writing clients supporting Hypermedia (imagine writing Java Swing-based client application for example). With WADL this task is completely automated, and it's a huge advantage in my view. Testing becomes a way easier too.

16

Before I give my explanation, let me say that most pure REST extremists will deride it to the ends of the earth. I don't agree with them, as i'd rather get something done, but just so you know.

WADL is a description of a web service API, a little like WSDL is for SOAP type web services, that is designed to be more in tune with RESTful interfaces (something WSDL is poor at).

It's primary usage in my experience is to allow you to generate client code that can call the service (handy if it's a very large API, which literally saves hours of work). It also serves the purpose of documenting a REST-like interface.

3
  • 3
    Sure, that's a good answer. The resistance seems to be from hardcore SOAP folks, who don't want REST at all, and some hardcore REST cowboys, who don't want any extra make-work. Having a formal doc is a good fig leaf to have in an "enterprise", even if it's a waste of time for a tiny API in a start up.
    – Roboprog
    Oct 27, 2011 at 23:05
  • 1
    In my experience, there are three main reasons for something like WADL: - a lot of good developers don't know REST. - When your on the clock, having a document or API speeds things up enormously. - You can never assume someone else has implemented a REST call the same way you would. Even REST evangelists can't agree :) I've even run across cases where an environment won't allow a DELETE or PUT call to execute, so you get a REST-like interface that only uses GET and PUT calls... and then the documentation become crucial. Oct 31, 2011 at 18:51
  • I'm sure you meant GET and POST, as in faking PUT and DELETE with funky POST options. Alas...
    – Roboprog
    Nov 2, 2011 at 17:41
7

REST specifies nothing about WADL.

2
  • I think so, but Wadl can use inside of the rest for example youtube.com/watch?v=cDdfVMro99s . It seems that wadl supports clients to use server's function. And clients can just need to have parameters and the name of the function.
    – Iguramu
    Aug 21, 2009 at 19:41
  • 7
    What you just described to me sounds like RPC, not REST.
    – aehlke
    Aug 21, 2009 at 20:45
3

When you want to expose the REST services ,the best way is to generate WADL and share with consumer(similar to WSDL in SOAP based web services).WADL is used to describe service all in on place.

0

WADL is not necessary to use. But, If you are working with complex existing application and you want to implement REST service call by replacing the EJB/SOAP service call, Then it is very safe and good practice that you use WADL. By using WADL generate client side java stubs you will be in sync with the service.

You can generate client side java stub using WADL file with help of wadl2java maven plugin.

Not the answer you're looking for? Browse other questions tagged or ask your own question.