[Corona] Corona WADL
Geert Josten
geert.josten at dayon.nl
Wed Mar 7 22:51:06 PST 2012
:-D
I did commit earlier work, but I was playing with semi-automated testing
using SOAPui too. That way I could also make sure that Corona actually
behaves like described in the WADL. I had to make some intrusive changes to
improve those results. I can commit, but am not entirely sure about the
status. I believe things kind of work, you can even load the soapui-project
directly from Corona, but if you run the tests most still fail, because the
endpoints config isn’t tight enough yet..
Note also that my branch is behind a few months..
Perhaps best I’ll just commit and you take a look whether you think it is
worth fixing my branch so it could be pulled or that you will just copy
interesting bits?
Kind regards,
Geert
*Van:* Eric Bloch [mailto:Eric.Bloch at marklogic.com]
*Verzonden:* donderdag 8 maart 2012 1:31
*Aan:* Geert Josten
*CC:* Ryan Grimm; Scott Stafford; Jason Hunter;
corona at developer.marklogic.com
*Onderwerp:* Re: [Corona] Corona WADL
So it turns out I"m playing with the apigee api console builder and lo and
behold... the input for the console is a WADL.
Did you end up committing your work into a fork, Geert?
-Eric
Eric Bloch
Director, Community
MarkLogic Corporation
desk +1 650 655 2390 | mobile +1 650 339 0376
email eric.bloch at marklogic.com
web developer.marklogic.com
twitter @eedeebee
On Dec 10, 2011, at 5:54 AM, Geert Josten wrote:
A few more thoughts struck me..
First is the difficulty with the uris that are more complex regex
patterns. The facet pattern is pretty wild. I think I'll need to
introspect the facet configuration to generate a more useful WADL.
Second is that I stumbled on my earlier work on WADL, and saw I also did
some work auto-generating a SOAPui XML Project file, with various test
cases for all endpoints. Great for doing automated testing.
Kind regards,
Geert
-----Oorspronkelijk bericht-----
Van: Ryan Grimm [mailto:grimm at xqdev.com]
Verzonden: vrijdag 9 december 2011 23:55
Aan: Geert Josten
CC: Scott Stafford; Jason Hunter; corona at developer.marklogic.com
Onderwerp: Re: [Corona] Corona WADL
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
_______________________________________________
Corona mailing list
Corona at developer.marklogic.com
http://developer.marklogic.com/mailman/listinfo/corona
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://developer.marklogic.com/pipermail/corona/attachments/20120308/9e77230e/attachment-0001.html
More information about the Corona
mailing list