If you must make an API available over a network or over the web, you've got a number of ways to do it. Conventional wisdom these days argues for WS-*, SOAP, SOA, and their ilk. These have a lot of power, but, to be honest, I'm much more likely to use something simple: XML over HTTP.
I'm not going to get into a discussion about the pros and cons of a WS-* approach vs. XML/HTTP, nor the theories behind REpresentational State Transfer. There are lots of places you can go for that.
However, if you are building or consuming APIs using XML over HTTP, it may have occurred to you that there's no consistent way of documenting and describing these services. WADL, the Web Application Description Language, attempts to fill that gap, and it seems relatively sensible.
I'm a little wary, because I've had to create and consume WSDL, and I'm not yet convinced that a description language adds enough value to warrant any additional complexity to the XML/HTTP stack. That said, it's interesting to the applications people have considered for such a thing:
- Generating Documentation from WADL
- WADL from Examples (e.g. in Documentation)
Of course, there are alternatives. If you're writing XML over HTTP, are you considering a description language?