WADL or WSDL 2.0

[Carlos Eberhardt]

Does anyone have opinions on the benefits of using WADL or WSDL 2.0 to describe restful services? I'm in an "enterprise" that's used to SOAP, so WSDL is assumed and challenging assumptions can be .. challenging. ;)

I'm just not sure there's utility in spending time creating WADLs for endpoints. On the other hand, internal discussions about using WADL as a design tool.. a top-down approach to defining endpoints, seem to make sense. Anyone out there using WADL?

Thanks!

Carlos

[The Amiable API]

Hi Carlos:

I cannot answer your question, but I'm glad that I can chat with
someone in an "enterprise" like myself. It looks like we are dealing
with very similar issues.

Here is my (admittedly much more general) formulation of the problem.
There is no WS-* stack in browsers or in handheld devices, so teams on
such projects cannot leverage existing SOAP interfaces.Add-hock,
poorly designed and inconsistent small RESTful APIs start popping up
everywhere and before long IT needs to formulate a REST strategy. IMO,
if you take all the requirements that drove the evolution of SOAP for
the past decade, you end up with the entire WS-* stack re-implemented
as JSON resources. I'm old enough to see it happen before. The WS-*
stack is essentially the re-implementation of (almost) all enterprise
middleware features from the previous decade (the 90's). Similar
requirements tend to lead to similar solutions, save some relatively
low-level technical details.

Coming back to your question. I would be very curious to know what
application are you considering WADL for? Web, mobile, back-end
integration? Can you imagine a world where we can use REST where it
makes sense and SOAP where we already do? Do we really need to ditch
SOAP and in the process ruin REST for everybody else with our
enterprise requirements? These are questions that keep me up at night
(figuratively speaking, of course). Any insights?

Cheers,

Ferenc

On Nov 30, 5:39 pm, Carlos Eberhardt <carlos.eberha...@gmail.com>
wrote:

[Carlos Eberhardt]

Sorry for the delay in responding. Enterprise.. 'nuff said? ;)

To your questions, these are the same questions I'm asking myself. I'm in the lucky position of influencing direction for a fairly large set of web services. So far, I've stated we should prefer a restful architecture for web services unless we find a need to do something else. The problem I'm running into is the SOAP bias... the expectation of a WSDL for any web service, regardless of whether it's SOAP. So, right off the bat there's a cognitive bias challenge. What I'm hoping to do is steer the documentation discussion to focus on the response, and not the call. But, I'm going to have to give something up, so I'm hoping to find for set of lightweight documentation templates that will satisfy people without introducing unnecessary coupling and hopefully raising some awareness about how the restful style is different. I thought WADL might fit that bill, but the more I look into it the less I think it will. Interested to hear what other people are doing here in terms of standards, documentation, etc. 

[Chris Matthieu]

It's always been my understanding that WADLs are for REST APIs and WSDLs are for SOAP.

-Chris

[Jordan Reed]

Our organization has a full WS-* stack (WSDL, SOAP, ...) for our
server-to-server communication for enterprise.

We have launched a developer API set using REST w/ XML response to be
consumed by HTML, Flex, mobile, etc. We looked at generation of WADL/
XSDs along with it. Coming from a SOAP background it seemed to make
sense, and everyone though, "great our developers will use a toolset
to generate client libraries and then be good to go." But from what
we can tell, no one does this - and that toolset doesn't really exist.

So we did create XSD for all the responses, but we don't generate the
WADL any more and no one is asking for it.

..Jordan

On Dec 6, 8:15 am, Carlos Eberhardt <carlos.eberha...@gmail.com>
wrote:

[Tino]

we are also designing a REST API for the first time,
me personally coming from SOAP, but the rest of the team not.

Especially given the fact that the dev is partly done by a 3rd party,
I do feel a lack of interface documentation in REST world,
compared to SOAP, so
I started using SOAPui to "define" the API and write tests to
define the expected behaviour.
SOAPui is able of creating a WADL and nice HTML formatted
documentation.

I take the created WADL as a start an put further info into it,
especially about expected headers etc, what SOAPui can't do.

having said that, I expect the REST API to be more "self-explanatory"
than a SOAP one,
but that's yet to be proven.

maybe that is useful to you, too?

cheers,
Martin

[Sam Ramji]

A few things are going on in API description languages currently, and there's not really critical mass one way or the other.  Partly I think this is because there's still a lot of API client development done in Notepad.txt rather than formal IDEs... as a result there's little demand for a standard definition language.  Partly it's because REST is a style and not a protocol, so the expectations of a "one true way" and a "perfect description" are not present.

There's a deeper discussion at the following group: 

http://groups.google.com/group/api-description?pli=1

The key in picking something at this point is to be super clear on your goal:

1) For just documenting your API based on your code: have you looked at the Swagger framework from the Wordnik guys for that purpose?

http://swagger.wordnik.com/ 

It's like the "son of javadoc" for REST and is pretty slick.

2) For being technically complete and having machine readability/tools support, WSDL 2.0 doesn't seem more appropriate than WADL for documenting a REST API. Then again describing a JSON API using XML is like dancing about architecture, to torture the old saying.  

3) For enabling automatic type and content validation, there are two approaches: for XML APIs then XSD lets you use existing libraries to validate the request and response; the Google guys are using a description language that incorporates JSON Schema to help do the same thing.

At Apigee we ended up defaulting to WADL because we have Java infrastructure, there are easy WADL readers and writers for Java, and we handle so many APIs that we had to have a consistent format and didn't think we should do one from scratch.  WADL itself was short of a number of features we needed, so we ended up extending it (for example, with indicators for reasonable default values, security protocol such as OAuth, and links to original human-readable documentation).  We needed this because we're an API tools builder - not because we were trying to find a great away to describe our own service to 3rd parties.  We use this to drive the tool at http://apigee.com/providers.

All of the WADL files we've built to describe Twitter, Facebook, bit.ly, Etsy, and others are open source and can be found here: https://github.com/apigee/wadl-library

I am hoping that the purposes of API providers, API tools builders, and API client developers can be met through a common convention - but too quote Greg Brail, "we shouldn't go too far down this path because we'll just end up with SOAP 3.0."

Cheers,

Sam

[G. Hussain Chinoy]

That's a great and very helpful response, Sam.

For our enterprise, we were looking for WADL or WSDL 2.0 to do "interface first" design, which we'd used to some level of success for our SOAP/WSDL, and now with a majority of the new services being REST-based, I thought there might be some utility in these standard definitions. I'm not sure how far away we are from automatic consumption of REST-based services via a description language, though. Seems like a lot of the SOA governance/ESB providers are a bit confused by REST, but that's another topic.

I do think, though, in the meantime, being able to have some method of consistently providing documentation for these services is a massive use to both the providers and the consumers. Sam - are you using SOAPui to generate the WADLs for those apis?

I'd love to hear more experiences from folks who use WADL or WSDL 2.0 for design.

[Chris Chris]

tl;dr  Not sure WADL's are all that helpful, even though I want them to be; Documentation is key!

The API development I have been involved with has these same problems. I have dealt with WSDL's in the past and even tried, as I am sure we all have at one point, to bend it to work in a "RESTful" manner - which just seems like a monumental (and yes: "dancing about architecture
") ... WADL seemed like such an amazing promise from the WSDL pattern for a REST architecture (at least I thought so). Currently, we do generate WADL from our internal (PHP/Drupal) services definition (which has been a task in its own right compared to what is evidently available with Java tooling), and this has been nice; particularly as a manner to expose a "technical interface" of our internal definition.

We take that WADL and immediately process it through an XSLT (wadl_stylesheets or wadl-stylesheet) which results in "not bad" documentation (really it's just HTML of the generated XML). Again, this is really quite technical - a nice reference, but not really suitable to handoff as usable documentation; we have toyed with using the WADL to "generate" a test-console, as it seems the https://github.com/apigee/wadl-library are "able" to plug into apigee console, but as Sam mentioned: they've "extended it" with additional metadata that is really necessary for the console to be fully usable.

We have also taken the WADL and tried to process it through "code-gen" to try and generate language specific "libraries" (e.g. rest-api-code-gen), but this really generated sub-par boiler-plate (sample). I suppose this could be improved with some contribution to the code-gen libraries... (although, I have been more curious about using the description as more of a configuration like in blackwinter wadl.rb ).

Documentation seems key to me (agreeing strongly with tools like Swagger); and we have actually been using the WADL to *help* generate some of the restful documentation - basically a couple of makefiles in the documentation area to pull in updates. IMO this actually works nicely, and the technical side of me really enjoys the idea that there is a "standard" (WADL) representation backing the docs.