Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm about to embark on a project that makes extensive use of a properly RESTful approach. That is, it uses HATEOAS and serves up resources in a manner that allows for general exploration by a client.

I would like to ensure that I provide a description of my endpoints in a manner that would allow client applications to be automatically generated in a wide variety of languages. I understand that for SOAP based web services I can use WSDL and that apparently there is WSDL2 that provides greater definition of the HTTP verbs in use with REST. However I see many articles swinging back and forth over it's utility.

So, should I use WADL to allow external code generators to quickly build a client for my web application or is there a better standard that is expected?

share|improve this question
    
Wow - 2 days and just the quiet rustling of the wind through the tumbleweeds... –  Gary Rowe Feb 6 '12 at 10:30
add comment

2 Answers

up vote 11 down vote accepted

My advice is not to bother. WADL has not been that widely adopted See this question on Stack Overflow and there are some strong views that's it's not a good fit with the kind of 'proper' REST you describe, as shown here on another Stack Overflow question.

WADL descriptions are time consuming to build (and mostly manual) and they add a brittleness that HATEOAS is designed to avoid - i.e. you'll have some well defined entry points but exactly how your client proceeds is then determined by opaque links, not a predefined 'contract'.

That's not to say you should run away entirely from documentation, schema definition, etc, though theres an end of the RESTifarian spectrum that would suggest you can approach such a high level of self-description you don't need them. I've not found this to be the case in practice. A few solid worked examples should be all an unfamiliar developer needs. And knock up a few clients for your own API to try it out (easy enough from JQuery). That will give you a good indication whether you're building something consumable or not.

A good source of information in this area is the Hypertext Application Language. I find some of it a little heavyweight, but the debates on the mailing list are good and current and relevant.

Hope that helps you get started.

share|improve this answer
1  
+1 for a good answer. This confirms the suspicions that I've been having about it and re-inforces my current approach (consume your own API to see how rubbish it really is). –  Gary Rowe Feb 7 '12 at 10:37
add comment

The state of REST interfaces as driven from anything other than an interactive browser isn't very good. HATEOAS is a nice principle, but it leads to interfaces that are very strongly people-oriented and it tends to lead to the burden of the user interface being put on the service developer (who is usually pretty busy making the service itself work).

WADL itself isn't too great; it doesn't really capture enough of the semantics of the service to make it possible to tool things up. Of course, this is a hard problem in general. WSDL rarely exposes enough information either, and that's had a lot more effort put into the problem (it's possible to attach enough information, but hardly anybody actually does so).

Yet it is telling that a colleague of mine has spent months working on a library that uses a REST interface to a service, and the WSDL-described interface to the same service[*] was tooled automatically to nearly the same quality in seconds; going the rest of the way was about a day of writing wrapping classes. My hunch (based on a limited sample size) is that you cannot get rid of all brittleness in a complex service because the semantics of the service will inevitably evolve over time, and that REST is better at driving interfaces for humans while SOAP is better for interface libraries (there's good WSDL/SOAP client tooling for almost all languages of note). Unless you've got the luxury of doing both, which one to focus on should depend on which set of clients you care about most.

I wouldn't put much effort into WADL, but if your REST framework will produce it for you (Apache CXF does this) then there's no particular reason to not provide it. Anyone who wants to tool off your code will want WSDL+SOAP.


[*] As the author of the service in question, I can say for sure that both interfaces supported the same operations — there was a common underlying abstract model — and in a “natural” style for both interface types. On the service side, it was definitely the case that some things were easier with REST and others with SOAP.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.