[Corona] Corona WADL

Fri Dec 9 14:54:48 PST 2011

Hi Geert,

The schema for the endpoints definition out of ml-rest-lib (the library we're using: https://github.com/marklogic/ml-rest-lib) actually has options for declaring the type, if a parameter is required and if it can be specified multiple times.  For example take a look at the DELETE definition for /store in Corona:

    <request uri="^/store/?$" endpoint="/corona/store.xqy">
        <http method="DELETE">
            <param name="stringQuery" required="false"/>
            <param name="structuredQuery" required="false"/>
            <param name="bulkDelete" required="false" as="boolean" default="false"/>
            <param name="include" alias="include[]" repeatable="true" required="false"/>
            <param name="limit" required="false" as="integer"/>
            <param name="outputFormat" required="false" values="json|xml"/>
        </http>
    </request>

You can see that the limit parameter is declared as an integer and that it isn't required.  You can also see that the include parameter is specified to allow multiple values.  By default value of the required attribute is true and repeatable is false.  If a type isn't specified for parameter xs:string is assumed.

Does that help with some of the needed info?

--Ryan

On Dec 9, 2011, at 2:40 PM, Geert Josten wrote:

> Interesting idea indeed, I immediately looked into generating a WADL from
> it. Building the skeleton is very easy, actually. Things I am lacking for
> an improved WADL are parameter types (including whether they are optional
> or not, which could be added to the type as ? or *), and response (mime)
> types of each call. And optionally what kind of error responses one could
> expect (like 404, etc..)
> 
> Kind regards,
> Geert
> 
> -----Oorspronkelijk bericht-----
> Van: Scott Stafford [mailto:Scott.Stafford at marklogic.com]
> Verzonden: vrijdag 9 december 2011 22:34
> Aan: Geert Josten; Jason Hunter
> CC: corona at developer.marklogic.com
> Onderwerp: RE: [Corona] Corona WADL
> 
> I realized today that you could write a decent interface documentation (or
> WADL-like docs) by just transforming the endpoints config variable (see
> endpoints.xqy).  I need to put together some interface documentation for
> some consumers and I found that most of the work was already done for me.
> A short transform to HTML is below as an example.
> 
> One request I would have would be to add some additional metadata to this
> endpoint xml variable.  I would like to see a name variable and a
> description variable.
> 
> <options>
>  <request uri="^/search(/)?$" endpoint="/corona/search.xqy">
>    <name>search</name>
>    <description>find stuff</description>
>     <param name='txid" required="false">
>        <description>a transaction id</description>
>    </param>
>  </request>
> </options>
> 
> ---------------TRANSFORM ENDPOINTS TO HTML-------------
> xquery version "1.0-ml";
> import module namespace endpoints="http://marklogic.com/corona/endpoints"
> at "/corona/config/endpoints.xqy";
> declare namespace rest = "http://marklogic.com/appservices/rest";
> (
> xdmp:set-response-content-type("text/html"),
> <html>
> {
>  for $request in $endpoints:ENDPOINTS/rest:request
>  let $endpoint := <p>{ fn:string($request/@uri) }</p>
>  return
>  (
>    $endpoint,
>    <table>
>      <tr>
>        <th>Name</th>
>        <th>Required</th>
>        <th>Type</th>
>      </tr>
>    {
>      for $i in $request//rest:param
>      return
>       <tr>
>         <td>{ fn:string($i/@name) }</td>
>         <td>{ fn:string($i/@required) }</td>
>         <td>{ fn:string($i/@as) }</td>
>       </tr>
>    }
>    </table>
>  )
> }
> </html>
> )
> Scott A. Stafford
> Consultant
> MarkLogic Corporation
> scott.stafford at marklogic.com
> Cell:  +1 703-216-9459
> www.marklogic.com
> 
> This e-mail and any accompanying attachments are confidential. The
> information is intended solely for the use of the individual to whom it is
> addressed. Any review, disclosure, copying, distribution, or use of this
> e-mail communication by others is strictly prohibited. If you are not the
> intended recipient, please notify us immediately by returning this message
> to the sender and delete all copies. Thank you for your cooperation.
> ________________________________________
> From: corona-bounces at developer.marklogic.com
> [corona-bounces at developer.marklogic.com] On Behalf Of Geert Josten
> [geert.josten at dayon.nl]
> Sent: Monday, December 05, 2011 7:37 AM
> To: Jason Hunter
> Cc: corona at developer.marklogic.com
> Subject: Re: [Corona] Corona WADL
> 
> I'll see if I can find a spare moment, and look into WADL and generated
> clients myself. Keep you posted..
> 
> Kind regards,
> Geert
> 
> -----Oorspronkelijk bericht-----
> Van: Jason Hunter [mailto:jhunter at marklogic.com]
> Verzonden: zaterdag 3 december 2011 19:34
> Aan: Geert Josten
> CC: corona at developer.marklogic.com
> Onderwerp: Re: [Corona] Corona WADL
> 
> On Dec 3, 2011, at 3:05 AM, Geert Josten wrote:
> 
>> Hi Jason,
>> 
>> You think a machine-generated client based on the WADL will be no good?
> 
> I have no experience with using WADL for that.  Do you?  Do you have a
> sample I could see?
> 
> I have experience writing my own clients, and it's not hard.  The Corona
> API is pretty small.  I feel like it'd be more work to deal with WADL than
> to just make the HTTP calls.  :)
> 
>> Writing one yourself would allow to add some extra abstraction, but most
>> people will be satisfied with a bare client. Or were you thinking in
> terms
>> of performance perhaps?
> 
> I plan on a good abstraction layer.  Underneath that will be a raw layer.
> The WADL could be used to construct the raw layer.  Or direct coding, old
> school.
> 
>> Another benefit of at least having a WADL is that people could generate
>> client-code for not only Java, but likely plenty more. Perhaps not the
>> best code, but it could give them a jump-start.
> 
> I'd like to see Java, .NET, and Ruby initially.  Thoughts on that welcome.
> 
>> And since the 'endpoints' have been chosen such that they won't change
>> often, the WADL is likely to be pretty static. Minimal effort I think. I
>> think I could scrape it together for you if you like..
> 
> If you want to explore that road, I'd be interested in what you find.
> Maybe I'm underestimating WADL.  I reserve the right to think it's nasty.
> :)
> 
> -jh-
> _______________________________________________
> Corona mailing list
> Corona at developer.marklogic.com
> http://developer.marklogic.com/mailman/listinfo/corona
> _______________________________________________
> Corona mailing list
> Corona at developer.marklogic.com
> http://developer.marklogic.com/mailman/listinfo/corona