Expose the semantics of the whole api as a wadl file + seft descripbing docs

[brendanheywood]

Wadl is fairly easy to work with and gives something a formal (and parse-able) spec for a rest api

https://en.wikipedia.org/wiki/Web_Application_Description_Language

Note there might be something more modern and better (I think the latest soap was attempting to have rest bindings as well)

Then the next step is you can apply an xslt to turn the xml definition into a working self documenting html page which includes little testing forms for each endpoint