Registry Functions: WADL?

[ChristianGruen]

We have just added a function rest:wadl to our RESTXQ Function Module, which includes a WADL description of all available services. One advantages over rest:resource-functions is that WADL also allows for comments on paths and parameters in the output. The following example demonstrates how the output for a function looks like:

Described RESTXQ Function:

(:~
 : This service creates a backup from the specified database.
 : @param $name Name of the database to back up.
 :)
declare %restxq:path("/service/backup/{$name}"
    function local:backup($name as xs:string) { ... };

XML Representation:

<application xmlns="http://wadl.dev.java.net/2009/02">
  <resources base="http://localhost:8080/">
    <resource path="/service/backup/{$name}">
      <method name="GET">
        <doc>This service creates a backup from the specified database.</doc>
        <request>
          <param name="name" style="query" type="xs:string">
            <doc>Name of the database to back up.</doc>
          </param>
        </request>
        <response>
          <representation mediaType="application/xml"/>
        </response>
      </method>
    </resource>
  </resources>
</application>

@adamretter what’s your opinion on this?

[adamretter]

Hi Christian,

It was always the intention to add WADL support but to make it optional. The problem with a function is it becomes much harder for it to be optional, unless we say that it can return an error/empty-sequence if WADL is not supported. I always intended to add an application.wadl auto-url which could be disabled, and or excluded by annotation. See here - https://wikis.oracle.com/display/Jersey/WADL

So the answer is, sure I like the idea, but how to make it optional in a sane way so that implementations are not required to support WADL

[ChristianGruen]

Hi Adam, thanks for the Jersey link. I didn’t find any information, though, how WADLs can be disabled or excluded. The only hint I found is described in this weblog.

Regarding the proposal to add a function, I like the error alternative, as it is done with various optional XQuery features. One other advantage I see for having a wadl function is that its result can be further processed in XQuery before it’s sent back as reponse. One could e.g. restrict the WADL output to admin users within XQuery.

[apb2006]

I find the WADL function useful, but it is not a replacement for rest:resource-functions as it does not provide a way to go from the endpoint to the location of the implementing XQuery module/function.

[ChristianGruen]

Thanks for your assessment. If I get it right, rest:resource-functions returns a document node containing all function signatures. Is there any more recent specification, or do you refer to this spec.?

[apb2006]

The specification seems to need a bit more detail to me :-)
I am going on this message: http://exist.2174344.n4.nabble.com/restxq-rest-resource-functions-return-value-td4660414.html

in particular

 <rest:resource-function xquery-uri="/db/code/api/data/original.xqm">
        <rest:identity namespace="http://jewishliturgy.org/api/data/original" local-name="list" arity="3"/>

shows both the REST url and the corresponding implementation location. I think this is useful information. Maybe the rest:resource detail needs to be fleshed out or maybe a custom element could be added to the WADL call.

[adamretter]

I had certainly intended to create a Schema for the result of rest:resource-function, but have not yet found the time. The output is currently as described in the email that @apb2006 found. Obviously the bug mentioned in the email about output parameters needs to be addressed too.