Comments on: To WADL or not to WADL

By: Constantine

Constantine — Thu, 28 Jan 2010 09:58:26 +0000

I think that WADL helps to implement clients in a client-server architecture. I imagine writing Java client for the complex HATEOAS web service with lots of possible states… With WADL this step can be completely automated, though you won’t have some state constraints. Same is true about test cases and documentation – nowadays there exist quite a few generators utilizing WADL, you can find some examples here.

Also, WADL gives you a standard way to document your interfaces. For example, you can specify not only the representations, fault codes and so on, but also (links to) some business constraints affecting the behavior of your server (you can attach documentation to any element in WADL, so it will be easier for your users to find it).

Speaking about your schema idea… It seems to me that transferring all the information about the service (allowed methods, fault codes, etc) is a bad idea (at least, it’s an overhead). Instead, it is better to provide only an URL pointing at some definition, for example to WADL Think of the schema itself – normally we don’t put its contents into every XML file, we use xsd:schemaLocation instead.

By: Rickoshay

Rickoshay — Tue, 04 Aug 2009 00:39:26 +0000

I’m sure various schema will emerge but it’s not something a REST architecture needs. The idea of opaque URIs seems to be a core value proposition of the architecture. REST separates the concerns of parsing URIs by making assuming they have no distinguishing characteristics.

GET and PUT are fine but what if we need to hop, skip and jump and if so how high or far, and what object are we presumably directing? The rich API accessible via RPC looks rather compelling to the average programmer at that point… until they look at JAX-RS.

So, JAX-RS makes it a breeze to implement the richness of behavior we are looking for by adding semantics to those otherwise meaningless URIs. Ad hoc interpretation works, but layering on some schema definition is fine, too. As long as it’s not confused with REST, no problem.

By: PB

PB — Wed, 27 May 2009 05:35:05 +0000

How about just a page with some examples of it in various permutations. I liked your idea of something "schema like" to describe the structured data when its not obvious. Really, its a human developer that will be gluing this together, code generators will only do so much (and poorly) so just make it friendly, humane.

By: Michael Neale

Michael Neale — Thu, 21 May 2009 23:49:30 +0000

How about just a page with some examples of it in various permutations. I liked your idea of something “schema like” to describe the structured data when its not obvious. Really, its a human developer that will be gluing this together, code generators will only do so much (and poorly) so just make it friendly, humane.

By: Darrel Miller

Darrel Miller — Thu, 21 May 2009 20:36:42 +0000

Sure, I put all sorts of meta data in my links. It is documented in the specification of my media type.
HTTP describes my verbs, my media types describe my nouns and the relationships between my nouns. What left is there for WADL to describe.

By: Marc Hadley

Marc Hadley — Thu, 21 May 2009 16:00:42 +0000

Its not true that WADL ignores HATEOAS and links. See my recent blog entry for an example:

http://weblogs.java.net/blog/mhadley/archive/2009/04/hateoas_with_wa.html

By: Craig McClanahan

Craig McClanahan — Thu, 21 May 2009 14:40:42 +0000

I happen to have asked Marc Hadley (JAX-RS spec lead, author of the WADL spec) about how WADL might be used to describe a REST service driven by self-discovered embedded links, rather than by URI template patterns. His response was, basically, you could do this but need to establish a convention on how to figure out which elements are links. His full comments were on his blog:

http://weblogs.java.net/blog/mhadley/archive/2009/04/hateoas_with_wa.html

By: billburke

billburke — Thu, 21 May 2009 14:11:27 +0000

@Darrel

I agree to a degree. You don’t think that we need allow, and failure-type metadata within your links for update relationships?

By: Darrel Miller

Darrel Miller — Thu, 21 May 2009 13:52:50 +0000

If you properly describe the media types you are using then you do not need WADL. All you need is the root url and the media type that url returns.

Imagine for a second that when building a RESTful interface you had a requirement that said all Urls must be just a GUID. i.e. http://example.org/0A29FF9E-7F9C-4437-8B11-F424491E3931

I find that once you remove the crutch of the descriptive url, how to document RESTful interfaces becomes clearer. I’m not saying descriptive urls are a bad thing, in fact I believe the structure of the Url is very important to the server. However, the client should not care what the url is.

By: billburke

billburke — Thu, 21 May 2009 13:24:51 +0000

@Stefan:

Interesting, correct me if I’m wrong, but the RFC does not solve the issues I’ve presented here. Also, I don’t see how its that useful. I would much rather have a well-formed link structure specific to the format I’m transmitting (XML/JSON) than have to embed the suggested format within, lets say an attribute or element in XML and further reparse it.