WADL: Describing RESTful Web Applications
Every so often, I tinker with developing little web apps, such as the OUseful book search, but never really document the API as well as I should.
So when I stumbled across Marc Hadley's Web Application Description Language Language (WADL), I saw an answer to some of my documentation problems.
The most recent thing I've been tinkering with is an RSS item webpage scroller, based on a tool I saw Brian Kelly from UKOLN use a few weeks ago, that scrolls through a list of websites (you'll need to enable pop-ups in your browser to use it). (I actually built a page that does something similar to Brian's tool quite some time ago that cycles through CRRN members' web pages, but it's not really reusable...)
The idea of the RSS feed scroller - which at the moment I have locked down to del.icio.us RSS feeds - is that you pass it a feed location stub and the scroller then cycles through the website items. So for example, here's what's popular on del.icio.us.
The service still uses a pop-up - when I get a chance I'll probably make it frame based - and is little more than proof of concept, but it's enough for the purpose of this post which if you remember is actually about WADL...
So - rather than use prose to describe how to call the service, how does this partial WADL fragment look?
Looking at this, a little bit of explamnation is required:
- q is the query that gets used in an expression of the form http://del.icio.us/$q - so it must point to an RSS feed (hmm - I could tweak that...)
- td is the time delay in seconds between showing each page. There is a separate (currently fixed) delay before starting the 'show' itself;
- num is the maximum number of pages to scroll through before going back to the start.
So when I stumbled across Marc Hadley's Web Application Description Language Language (WADL), I saw an answer to some of my documentation problems.
The most recent thing I've been tinkering with is an RSS item webpage scroller, based on a tool I saw Brian Kelly from UKOLN use a few weeks ago, that scrolls through a list of websites (you'll need to enable pop-ups in your browser to use it). (I actually built a page that does something similar to Brian's tool quite some time ago that cycles through CRRN members' web pages, but it's not really reusable...)
The idea of the RSS feed scroller - which at the moment I have locked down to del.icio.us RSS feeds - is that you pass it a feed location stub and the scroller then cycles through the website items. So for example, here's what's popular on del.icio.us.
The service still uses a pop-up - when I get a chance I'll probably make it frame based - and is little more than proof of concept, but it's enough for the purpose of this post which if you remember is actually about WADL...
So - rather than use prose to describe how to call the service, how does this partial WADL fragment look?
<resources>
<resource uri="http://http://ouseful.open.ac.uk/magpierss/scroller.php">
<operation name="ScrollRSSlinks" method="get">
<request>
<parameter name="q" type="xsd:string" required="true" />
<parameter name="td" type="xsd:integer" />
<parameter name="num" type="xsd:integer" />
</request>
<response>
<representation mediaType="text/html" />
</response>
</operation>
</resource>
</resources>
Looking at this, a little bit of explamnation is required:
- q is the query that gets used in an expression of the form http://del.icio.us/$q - so it must point to an RSS feed (hmm - I could tweak that...)
- td is the time delay in seconds between showing each page. There is a separate (currently fixed) delay before starting the 'show' itself;
- num is the maximum number of pages to scroll through before going back to the start.
0 Comments:
Post a Comment
<< Home