On REST: WADL or not IDL, is the following approach right?

Question

This question is a bit long, please bear with me. In REST, i think we should not need WADL or any IDL. But rather something that would implicitly cover its concept. The way I think about it is when we (humans) surf the Web, when we go to a web site for the first time, we don't know what services it provides. You discover those on the html home page (or a sitemap page in a help section) or maybe just the main menu on the home page. If you make an analogy, the homepage or site map to us humans is what WSDL is to WS-* or what WADL could be to a REST service. Only that its just like any other html content. I think that in REST the following is a good way to do things, respecting the HATEOS paradigm. Have a top level (or default) resource that lists links to your other resources. For a library example, say RestLibrary.com/ it could be something like:

<root xmlns:lib="http://librarystandards.com/libraryml">
<resource class="lib:book">
  <link type="application/vnd.libraryml+xml" template="mylib.com/book/{isbn}" />
  <link type="application/vnd.libraryml+xml" rel="add" href="mylib.com/book" method="POST" />
  <link type="application/vnd.libraryml+xml" rel="update" template="mylib.com/book/{isbn}" method="PUT" />
</resource>
<resource class="lib:bookList">
  <link template="mylib.com/book?keywords={keywords}" type="application/vnd.openlibrary+xml" rel="search" />
</resource>
</root>

Note that it is assumed that the media type "application/vnd.libraryml+xml" is a defined standard or (may be just proprietary vocabulary) named libraryml. Also, the client should be able to understand this "homepage" resource (elements root, resource and link). This is the part that could be used instead of WADL : an Abstract vocabulary that should be understandable by any client. You could use an existing standard like Atom for example. But the main idea is to have an abstract vocabulary understandable by any client. Why not WADL then ? well wadl is only for service discovery. The idea here is to have an light abstract vocabulary that would serve as a base for hypermedia. A "root" vocabulary. Like in owl we have owl:thing...etc Now if the client knows the "libraryml" standard it can follow the links to the things it understands (after parsing the media type properties and xmlns). If not, it just won't.

When i can't understand how to deal with something in REST architecture i tend to see how we Humans do it in the Web. In the Web, we have the Generic language that is HTML that enables site builders to deliver any specific content, regardless of its meaning to the client (the user), Browsers understand HTML but not the "meaning" of its content. It is the user that understands the (domain specific) content. If i go to say QuantumPhysics.org, my browser can render the home page (it is just html after all) and i can read the home page. If i understand quantum then fine i can continue browsing. If i don't i just get out (unless i want to learn the hardway :) )

• In the RetsLibrary.com example the client app is just like me+my browser
• on QuantumPhysics.org. the media type "application/vnd.libraryml+xml" is quantum physics (knowledge).
• http is http in both examples.
• Now HTML of QuantumPhysics.org is in RestLibrary.com is XML + that tiny little abstract vocabulary (root resource and link, that you could replace with something like Atom).

So does this approach have any value ? don't we need a root tiny hyper-vocabulary so we can succeed with hypermedia and the "initial URI" concept ?

edit Yeah why not RDF as the root vocabulary !

Answer 1

Yes, I definitely see the need for this type of media-type.

We were talking about this exact type of thing on the freenode IRC REST channel the other day after Mike Kelly suggested the need for a "Hypermedia Application Language" application/hal+xml

See http://restafari.blogspot.com/2010/06/please-accept-applicationhalxml.html for an example.

RDF seems like overkill for this type of thing, but I would be happy to be proved wrong. I find RDF more focused on Linked Data than HATEOAS.