Totally agree.

Note that we are using WADL today to create documentation artifacts. So
http://api.openstack.org/ is generated from WADLs as are good chunks of the
books on http://docs.openstack.org/. We're also using WADL for validation and
testing at Rackspace internally, and I'm sure other folks are doing similar
things. There are definite practical advantages *today* to having a machine
readable artifact. Given that, I don't think Liem's request for a WADL is
unreasonable. Sure, WADL has it's problems, and once a viable alternative
emerges, I'm sure it will be supported. In fact, having a machine readable
artifact has the advantage in this regard, in that it we can auto-convert away
from WADL when/if we need to.

-jOrGe W.

On Jun 15, 2012, at 7:35 AM, Doug Davis wrote:

I don't see this as an either-or type of thing.

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.

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.

thanks -Doug

______________________________________________________ STSM | Standards Architect | IBM Software Group (919) 254-6905 | IBM 444-6905 | du...@us.ibm.com<mailto:du...@us.ibm.com> The more I'm around some people, the more I like my dog.

Mark Nottingham <mn...@mnot.net<mailto:mn...@mnot.net>> Sent by:
openstack-bounces+dug=us.i...@lists.launchpad.net<mailto:openstack-bounces+dug=us.i...@lists.launchpad.net>

06/14/2012 08:20 PM

To "Nguyen, Liem Manh" <liem...@hp.com<mailto:liem...@hp.com>> cc "open...@lists.launchpad.net<mailto:open...@lists.launchpad.net>"
<open...@lists.launchpad.net<mailto:open...@lists.launchpad.net>> Subject [Openstack] WADL [was: v3 API draft (update and questions to the
community)]

Hi Liem,

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.

Even back then, there was a lot of discussion in the community; e.g., see: http://bitworking.org/news/193/Do-we-need-WADL http://old.nabble.com/Is-it-a-good-idea-to-make-your-WADL-available--tc6087155r1.html http://www.25hoursaday.com/weblog/CommentView.aspx?guid=f88dc5a6-0aff-44ca-ba42-38c651612092

I think many of the concerns that were expressed then are still valid -- some
even within these limited uses. In no particular order:

* 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.

* WADL's primitives are XML Schema datatypes. This is a horrible match for
dynamic languages like Python.

* 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.

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.

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.

Cheers,

On 15/06/2012, at 2:08 AM, Nguyen, Liem Manh wrote: