openstack team mailing list archive

[John Dickinson <me@xxxxxx>]

I am concerned about some of the implications that are being discussed.

1) A WADL is part of documentation of an API. Nobody is going to object to more documentation.

2) Being an open-source project, if somebody wants to commit to creating and maintaining a WADL for a particular part of Openstack, they are free to. Alternately, persuade somebody else to do it. However, having a WADL to describe a particular component of openstack is not something that can be forced onto that component. Phrases like "All services should have WADLs" are either meaningless (unenforcible or not really all services) or oppressive (mandating requirements on a project).

3) A WADL is not a replacement for any sort of dev documentation, and in fact, still requires there to be human-readable dev docs.

Specifically for swift, not one of the current developers are going to either write or maintain a WADL for the swift API. However, we'll be happy to assist anyone who wants to write and maintain docs for swift, including WADLs.

The important thing is that code talks. If you want WADLs (or your flavor of WADLs), make them! Stop trying to architect systems for architects. These things are meant to be used. Let's focus on what is necessary for getting a reliable system into the hands of those who will be using it.

(Just about all of the above goes for things like API versioning, too. And packaging vs tarballs vs python libraries. And polling vs pushing. And the true meaning of what a ReST interface is.)

--John

Attachment: smime.p7s
Description: S/MIME cryptographic signature