openstack team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

I don't mind generating a WADL so long as we have a good expressive tool for doing so.  I haven't found one yet. There was a project a while back for doing so called "Rest Described and Compile" that seemed to be heading in the right direction, but it hasn't been worked on in a while.

http://tomayac.de/rest-describe/latest/RestDescribe.html

You used a GUI like interface to describe your REST service and it filled in all the XML for you.  I really like that approach.

SOAP UI,  also allows you to develop a WADL via a UI.

http://sourceforge.net/projects/soapui/

The UI there is kinda crappy, and there are a lot of features of WADL that don't get exposed.  Still you can use it to build a template of your WADL.

 What I would like to have in a WADL generating tool is the ability to add RST, wiki, docbook  descriptions and documentation,   as well as example JSON and XML payloads.  That would be really cool, but there's no tool that does that just yet.

In the interim, though,  we have to develop in XML.  Tools like Oxygen help a lot especially if you configure it with David's WADL plugin, which help catch a lot of errors early and help you fill in the blanks.    I know that we have plans to extend the plugin to add new features, so that should also help as well.

-jOrGe W.

On Oct 26, 2011, at 7:17 AM, Sandy Walsh wrote:

> As discussed at the summit, I agree there should be some form of IDL (WADL being the likely candidate for REST), I think manually crafting/maintaining a WADL (or XML in general) is a fools errand. This stuff is made for machine consumption and should be machine generated. Whatever solution we adopt, we should keep that requirement in mind.
> 
> $0.02
> 
> -S
> 
> ________________________________________
> From: openstack-bounces+sandy.walsh=rackspace.com@xxxxxxxxxxxxxxxxxxx [openstack-bounces+sandy.walsh=rackspace.com@xxxxxxxxxxxxxxxxxxx] on behalf of Mellquist, Peter [peter.mellquist@xxxxxx]
> Sent: Wednesday, October 26, 2011 2:06 AM
> To: Joseph Heck; openstack@xxxxxxxxxxxxxxxxxxx
> Subject: [Openstack] +1,  All services should have WADLs
> 
> Excellent topic Joe, thanks for bringing this up.
> 
> There are two main perspectives on WADLs: WADLs from a service developer point of view and WADLs from a cloud developer point of view. I consider the later the most important since we need to ensure that developers who write all the killer Openstack apps have first class API definitions. WADLs allow developers to utilize a standard definition of the APIs rather than dig through API documents which are often out of synch with the code. As shown in other projects, it is definitely possible to define all REST APIs in WADLs and then generate docs and code .. keeping everything in synch. Some implementation frameworks do not support REST / WADLs very well and this is where we hear the most complaining from service developers for reasons to not support WADLs.
> 
> 'all the services should have a WADL somewhere describing the API.'  100% AGREE.
> 
> The topic of when an API should be defined is also important. Do we define an API / WADL 1) up front before the service is implemented, 2) in parallel with the impl, 3) or after the impl? I am an advocate of #1 or perhaps #2 but not #3 since #3 is just retrofitting an API on existing impl without any real API design considerations.
> 
> Peter.
> 
> 
> 
> 
> 
> -----Original Message-----
> From: openstack-bounces+peter.mellquist=hp.com@xxxxxxxxxxxxxxxxxxx [mailto:openstack-bounces+peter.mellquist=hp.com@xxxxxxxxxxxxxxxxxxx] On Behalf Of Joseph Heck
> Sent: Tuesday, October 25, 2011 12:42 PM
> To: openstack@xxxxxxxxxxxxxxxxxxx
> Subject: [Openstack] describing APIs for OpenStack consumers
> 
> I expect this is going to open a nasty can of worms... today we don't have a consistent way of describing the APIs for the various services. I saw Nati's bug (https://launchpad.net/bugs/881621), which implies that all the services should have a WADL somewhere describing the API.
> 
> I'm not a huge fan of WADL, but the only other thing I've found is swagger (http://swagger.wordnik.com/spec).  I have been working towards trying to create an comprehensive OpenStack API documentation set that can be published as HTML, not unlike some of these:
> 
>        https://dev.twitter.com/docs/api
>        http://developer.netflix.com/docs/REST_API_Reference
>        http://code.google.com/p/bitly-api/wiki/ApiDocumentation#REST_API
>        http://upcoming.yahoo.com/services/api/
> 
> To make this sort of web-page documentation effective, I think it's best to drive it from descriptions on each of the projects (if we can). I've checked with some friends who've done similar, and learned that most of the those API doc sets are maintained by hand - not generated from description files.
> 
> What do you all think about standardizing on WADL (or swagger) as a description of the API and generating comprehensive web-site-based API documentation from those description files? Does anyone have any other description formats that would work for this as an alternative?
> 
> (I admit I don't want to get into XML parsing hell, which is what it appears that WADL might lead too)
> 
> -joe
> 
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp