<br><font size=2 face="sans-serif">I don't see this as an either-or type
of thing.  </font>
<br>
<br><font size=2 face="sans-serif">Totally agree with Mark that the APIs
need to be more clearly documented and that should be independent of any
kind of IDL (ala WADL) artifact.  I say this mainly because I think
we always need to have something that's human readable and not machine
readable.  There will always be semantics that can not be expressed
via the machine readable artifacts. Having said that, there are people
that like to have IDL-like artifacts for some kind of tooling.  So,
along with the well-documented APIs should be whatever artifacts that can
makes people's lives easier.  This means XSD, WASL, WSDL, etc... whatever
- pick your favorite.  </font>
<br>
<br><font size=2 face="sans-serif">No matter what artifact you choose to
use to guide your coding (even if its just the "well documented human
readable API doc"), you're still bound to that particular version
of the APIs.  Which means a change in the APIs/server-code might break
your client.  In this respect I don't think WADL or docs are more
or less brittle than the other.  To me the key aspects are the extensibility
points.  Once the APIs are deemed 'stable', we just need to make sure
that new stuff is backwards compatible which usually means defining and
leveraging well placed extensibility points. </font>
<br><font size=2 face="sans-serif"><br>
thanks<br>
-Doug<br>
______________________________________________________<br>
STSM |  Standards Architect  |  IBM Software Group<br>
(919) 254-6905  |  IBM 444-6905  |  dug@us.ibm.com<br>
The more I'm around some people, the more I like my dog.</font>
<br>
<br>
<br>
<table width=100%>
<tr valign=top>
<td width=40%><font size=1 face="sans-serif"><b>Mark Nottingham <mnot@mnot.net></b>
</font>
<br><font size=1 face="sans-serif">Sent by: openstack-bounces+dug=us.ibm.com@lists.launchpad.net</font>
<p><font size=1 face="sans-serif">06/14/2012 08:20 PM</font>
<td width=59%>
<table width=100%>
<tr valign=top>
<td>
<div align=right><font size=1 face="sans-serif">To</font></div>
<td><font size=1 face="sans-serif">"Nguyen, Liem Manh" <liem_m_nguyen@hp.com></font>
<tr valign=top>
<td>
<div align=right><font size=1 face="sans-serif">cc</font></div>
<td><font size=1 face="sans-serif">"openstack@lists.launchpad.net"
<openstack@lists.launchpad.net></font>
<tr valign=top>
<td>
<div align=right><font size=1 face="sans-serif">Subject</font></div>
<td><font size=1 face="sans-serif">[Openstack] WADL [was: v3 API draft
(update and questions        to the  
     community)]</font></table>
<br>
<table>
<tr valign=top>
<td>
<td></table>
<br></table>
<br>
<br>
<br><tt><font size=2>Hi Liem,<br>
<br>
I'm one of the folks who helped Marc get WADL off of the ground. At the
time, my use cases were exactly as you describe: documentation (e.g., <https://github.com/mnot/wadl_stylesheets>)
and testing.<br>
<br>
Even back then, there was a lot of discussion in the community; e.g., see:<br>
   http://bitworking.org/news/193/Do-we-need-WADL<br>
   http://old.nabble.com/Is-it-a-good-idea-to-make-your-WADL-available--tc6087155r1.html<br>
   http://www.25hoursaday.com/weblog/CommentView.aspx?guid=f88dc5a6-0aff-44ca-ba42-38c651612092<br>
<br>
I think many of the concerns that were expressed then are still valid --
some even within these limited uses. In no particular order:<br>
<br>
* People can and will use WADL to represent a "contract" to a
service (really, an IDL), and "bake" client code to a snapshot
of it in time. While it's true that the client and server need to have
agreement about what goes on the wire and what it means, the assumptions
around what guarantees WADL makes are not well-thought-out (in a manner
similar to WSDL), making clients generated from it very tightly bound to
the snapshot of the server they saw at some point in the past. This, in
turn, makes evolution / extension of the API a lot harder than it needs
to be.<br>
<br>
* WADL's primitives are XML Schema datatypes. This is a horrible match
for dynamic languages like Python.<br>
<br>
* WADL itself embodies certain patterns of use that tend to show through
if you design for it; these may or may not be the best patterns for a particular
use case. This is because HTTP and URLs are very flexible things, and it
isn't expressive enough to cover all of that space. As a result, you can
end up with convoluted APIs that are designed to fit WADL, rather than
do the task at hand.<br>
<br>
>From what I've seen, many developers in OpenStack are profoundly uninterested
in working with WADL. YMMV, but AFAICT this results in the WADL being done
by other folks, and not matching the reality of the implementation; not
a good situation for anyone.<br>
<br>
What we need, I think, is a specification of the API that's precise, unambiguous,
and easy to understand and maintain. I personally don't think WADL is up
to that task (at least as a primary artefact), so (as I mentioned), I'm
going to be proposing another approach.<br>
<br>
Cheers,<br>
<br>
<br>
<br>
On 15/06/2012, at 2:08 AM, Nguyen, Liem Manh wrote:<br>
<br>
> IMHO, a well-documented WADL + XSD would say a thousand words (maybe
more)...  And can serve as a basis for automated testing as well.
 I understand that the v3 API draft is perhaps not at that stage yet;
but, would like to see a WADL + XSD set as soon as the concepts are solidified.<br>
> <br>
> Liem<br>
> <br>
> -----Original Message-----<br>
> From: openstack-bounces+liem_m_nguyen=hp.com@lists.launchpad.net [mailto:openstack-bounces+liem_m_nguyen=hp.com@lists.launchpad.net]
On Behalf Of Mark Nottingham<br>
> Sent: Tuesday, June 12, 2012 8:43 PM<br>
> To: Gabriel Hurley<br>
> Cc: openstack@lists.launchpad.net<br>
> Subject: Re: [Openstack] [keystone] v3 API draft (update and questions
to the community)<br>
> <br>
> <br>
> On 13/06/2012, at 1:24 PM, Gabriel Hurley wrote:<br>
> <br>
>> Totally agree with all of Jay's points, and I also couldn't agree
more with Mark on the importance of being crystal clear, and not operating
on just a "common understanding" which is quickly misunderstood
or forgotten.<br>
>> <br>
>> Ideally I'd like to see an OpenStack API feature contract of some
sort... essentially a document describing the FULL list of features, how
those parameters are controlled and how they would interact, and what a
project should do if they do not implement an API feature (hopefully only
for technical reasons such as Keystone paging with LDAP or swift with complex
DB-esque operations). This isn't saying we should have a unified API spec,
I'm talking solely about a contract for the features all APIs should strive
to support.<br>
>> <br>
>> This would be a big project, but everyone would then have a common
agreement about what the user experience of interacting with OpenStack
should be. The project APIs as they stand are siloed and stunningly inconsistent,
and I'd love to work toward fixing that.<br>
> <br>
> Absolutely. <br>
> <br>
> One of my other projects is to rewrite the API as a proper specification
(in a style similar to an Internet-Draft, not that we'd necessarily publish
it as one).<br>
> <br>
> I should have something to show soon; if you're interested in helping
out, that'd be great.<br>
> <br>
> Cheers,<br>
> <br>
> <br>
>> My two cents,<br>
>> <br>
>>   - Gabriel<br>
>> <br>
>>> -----Original Message-----<br>
>>> From: openstack-bounces+gabriel.hurley=nebula.com@lists.launchpad.net<br>
>>> [mailto:openstack-<br>
>>> bounces+gabriel.hurley=nebula.com@lists.launchpad.net] On
Behalf Of<br>
>>> Mark Nottingham<br>
>>> Sent: Tuesday, June 12, 2012 7:20 PM<br>
>>> To: Jay Pipes<br>
>>> Cc: openstack@lists.launchpad.net<br>
>>> Subject: Re: [Openstack] [keystone] v3 API draft (update and
questions to<br>
>>> the community)<br>
>>> <br>
>>> <br>
>>> On 13/06/2012, at 3:31 AM, Jay Pipes wrote:<br>
>>> <br>
>>>> This isn't necessarily true. Nova's compute layer goes
through a number of<br>
>>> steps to ensure a semi-transactional nature to certain operations
like<br>
>>> resizing. Certain times a query needs to indicate that it
intends to make a<br>
>>> reservation of resources (see quota/reservation system now
.. this is the<br>
>>> SELECT FOR UPDATE paradigm) and other times, the query doesn't
care<br>
>>> about such things. In the latter case, there aren't expectations
that the list<br>
>>> returned is 100% accurate according to the state of the database
at a<br>
>>> particular timestamp of when the transaction occurred. In
this case, filters<br>
>>> and optimistic pagination works perfectly fine, IMHO.<br>
>>> <br>
>>> That might work, but we need to be crystal-clear about the
semantics of<br>
>>> what we're giving back; having it understood between OpenStack
projects<br>
>>> isn't good enough.<br>
>>> <br>
>>> I.e., we're not building the APIs just for Horizon; they're
for lots of folks, and<br>
>>> subtle semantics -- even when well-documented, much less when
they're<br>
>>> not -- are often misunderstood.<br>
>>> <br>
>>> Cheers,<br>
>>> <br>
>>> --<br>
>>> Mark Nottingham   http://www.mnot.net/<br>
>>> <br>
>>> <br>
>>> <br>
>>> <br>
>>> _______________________________________________<br>
>>> Mailing list: https://launchpad.net/~openstack<br>
>>> Post to     : openstack@lists.launchpad.net<br>
>>> Unsubscribe : https://launchpad.net/~openstack<br>
>>> More help   : https://help.launchpad.net/ListHelp<br>
>> <br>
>> <br>
>> <br>
>> _______________________________________________<br>
>> Mailing list: https://launchpad.net/~openstack<br>
>> Post to     : openstack@lists.launchpad.net<br>
>> Unsubscribe : https://launchpad.net/~openstack<br>
>> More help   : https://help.launchpad.net/ListHelp<br>
> <br>
> --<br>
> Mark Nottingham   http://www.mnot.net/<br>
> <br>
> <br>
> <br>
> <br>
> _______________________________________________<br>
> Mailing list: https://launchpad.net/~openstack<br>
> Post to     : openstack@lists.launchpad.net<br>
> Unsubscribe : https://launchpad.net/~openstack<br>
> More help   : https://help.launchpad.net/ListHelp<br>
<br>
--<br>
Mark Nottingham   http://www.mnot.net/<br>
<br>
<br>
<br>
<br>
_______________________________________________<br>
Mailing list: https://launchpad.net/~openstack<br>
Post to     : openstack@lists.launchpad.net<br>
Unsubscribe : https://launchpad.net/~openstack<br>
More help   : https://help.launchpad.net/ListHelp<br>
<br>
</font></tt>
<br>