This post is more than 2 years old.
Big thanks to Henry Ho for asking about this during my REST presentation earlier this week. Apparently, it is common for REST services to notice an OPTIONS request (by that I mean a request made with the HTTP verb OPTIONS) and return an XML-descriptor of the service. I don't believe our docs cover this, but the feature works quite well actually. Here's a few examples.
Let's start with a very simple REST service:
To get the descriptor, I wrote a quick test script:
How about a more complex service? This one demonstrates dynamic resources.
In the result, which I've cropped a bit due to the size, you can see that the dynamic nature of the sub resources are documented well.
And finally - here's an example of how "produces" is represented. Here's a snapshot of a larger REST service. This method is used to return an image of a product.
And here is how it is returned: