AWDL - Another Web Description Language
14
March
Alex Barnett asks about Web Description Languages for REST. Below is a simple example of my own interpretation based originally upon WADL, something I worked on and never did anything with some months ago. It follows the philosophy of least amount of validation, user and machine readable documentation and graceful depreciation. I got so far as to consider re-writing it as a microformat before I became lost in the concept that was the HTTP Extensions Framework (PEP).
Now I love the idea of having the ability to query a resource to find method queries with documentation I can use to interact with that resource. It’s here I believe a WDL may come in very useful. I say may because I wonder if resources themselves should have a Resource Description Language instead.
One of the problems I have with PEP is that pointing to some external language as it enables, adds another layer of fragility. It’s resources themselves that need to contain everything required to interact with that resource. Have a listen to Alan Kaye’s talk for a better explanation.
So using REST I would then simply perform a
GET / HTTP/1.1
Accept: xml/rdl
Host: example.com
Whereby something like my AWDL example is returned. It could however be an HTTP Form, microformat or XForm returned.
[xml]
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://example.com/awdl">
Reason: Parameter default value moved to document tag following the least amount of validation philosophy
Please update to version:
This will be unsupported as of:
Scheduled for removal:
[/xml]
This example shows a search query engine. Client parses and queries, however then a problem arises when querying again when a language change has occured.
Solutions include: query the RDL again or implement HTTP SUBSCRIBE, NOTIFY verbs. The latter client is then alerted of updates to a resources description language as they happen.
I also wonder if NOTIFY verbs should indicate when they’re a patch. Or whether that warrants additional verbs.
Now to make this developer friendly and not just machine friendly, the ability to query any resource and retrieve that documentation could be done with a simple extension. http://example.com/.rdl returning the resources description language. Or http://example.com/image.png.rdl could return operations one could perform on a png image. Ideally the RDL should be human as well as machine readable.
I’m hoping The Web Architecture Lab will address all of these much better than I ever could.
From Wikipedia, the free encyclopedia
An awdl is a long poem written in Welsh in one of twenty-four strict metres, using cynghanedd. Such poems are considered among the finest work that a bard can aim to produce, and prizes are given at eisteddfodau for the best awdl.
Hopefully someone wins the prize for best AWDL some day soon.