Mechanism for writing, packaging and getting the "interface description" (documentation) of restservices

[mpo]

We should be able to extract the list of available (exported) rest-services from any modules (packaged as jars). For each of these rest-services their uri-service-interface should be formally described so consumers of the services know which resources are present within them.

This will require a number of things

1. a formal way to describe rest-services (WADL might be an even more formal way to generate useable text/documentation from)
2. a convention for packaging this stuff within the module, and some way to assign this documentation to the actual exported restservice (embedded as wadl, html, or public uri)
3. some tool (maven-plugin) to introspect module-jars and produce the description of the available rest-services

[mpo]

additional thoughts in this area:

• this is potentially somewhat related to #28
• self-describing interfaces would also mean that the OPTIONS method is handled correctly (even taking into account authorization settings)
• another way of publishing these descriptions might be to actually put the documentation-resource closeby in the uri-space
  • potentially for validation (uri's expect a posted entity) we could use the GET to describe the purpose
  • or in general introduce some ?describe request-parameter

[mpo]

beyond 0.4 scope