[DALI] DAI-examples markup

[Patrick Dowler]

I'm no sure if anyone but Markus and Norman and I have thought about 
this section, but it has a lot of potential. However, we also have 
differing opinions on the details.

So, DALI-examples specifies how to markup an (xhtml) document so the 
exmaples for using the service are machine-readable. I have written a 
really simple bit of code that extracts the examples so they can 
actually be executed.

In the current PR (and my prototype impl and code to extract it) I 
include some things that RFC comments object to:

1. the http-action to perform (eg GET or POST)
2. the base-url you use for that action
3. a generic-parameter for wrapping/describing key=value pairs

So, the example job parameters are given using #3 and I like the idea of 
a general way to describe those (in the markup) rather than each service 
having to define specific markup properties.

#2 and #3 are there so the client app can actually "execute" the example 
with no other knowledge. This would allow a general purpose app to do 
something (short of handling all possible kinds of outputs, of course). 
An RFC suggestion is that the caller already knows the base URL for the 
service (to have found the <baseURL>/examples doc) so they don't need #2 
and #3, but since a service could have multiple types of jobs with 
different resource URLs, all under the same base url, and with different 
behaviour/semantics, they cannot actually know how to execute the 
example without more information.

Note: The current PR-DALI does not actually say if the semantics of that 
base-url are sync or async so it would actually be hard for generic code 
to run the example... so something more/different is needed in any case.


Alternatives:

A1: add yet another property saying that the action is sync vs async and 
keep the current 1-3

A2: include the capability the example exposes and the caller would then 
know exactly what the behaviour (sync/async, get/post) was and could 
find the required resource url in the VOSI-capabilities doc (if 
necessary -- would not be for TAP).  This would allow a generic bit of 
code to extract all the examples, but only an app that understood the 
capabilities would be able to execute them. That might be OK.

A3: is there a 3rd option? We have to assume that the examples document 
contains examples for using different sync or async resources that make 
up a  service...




-- 

Patrick Dowler
Canadian Astronomy Data Centre
National Research Council Canada
5071 West Saanich Road
Victoria, BC V9A 2L9

250-363-0044 (office) 250-363-0045 (fax)