← Back to team overview

openstack team mailing list archive

Re: +1, All services should have WADLs

 

Couldn't agree more with this

On a side-note, I'm now going to sign all emails as

Weird,

-Matt

On 10/28/11 12:54 PM, "Jay Pipes" <jaypipes@xxxxxxxxx> wrote:

>On Fri, Oct 28, 2011 at 1:39 AM, John Dickinson <me@xxxxxx> wrote:
>> 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.)
>
>Not sure what this means from a personal existential viewpoint, but I
>completely agree with John.
>
>Weird.
>
>-jay
>
>_______________________________________________
>Mailing list: https://launchpad.net/~openstack
>Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>Unsubscribe : https://launchpad.net/~openstack
>More help   : https://help.launchpad.net/ListHelp



References