RESTful service description

Question

From what I understand, I need to use WADL to describe a RESTful web service. Still, I have read many answers in relevant posts, where users are strongly opposed the use of WADL.

What are the disadvantages of WADL? Is there any alternative solution?

Answer 1

The HTTP spec tells you how to retrieve and update resources. Resources are identified by URIs and should be linked together, so all data should be discoverable from the service root url, just like pages on a web site. What that leaves is for you to document the media-types that you are transferring across the wire.

If you take this approach and you reuse media-types across services then you only need to document the media type once and it will be applicable for all services.

Once you have done those steps there is really nothing left for WADL to document.

If you want to do REST you cannot use WADL to code generate clients, as that creates a tight coupling between client and server. If that's ok with you, fine, but just realize that you are not doing REST and therefore will not realize some of the benefits of REST.