ColdFusion 10 REST and Self-Documentation
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:
Which gives:
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:
Thanks for examples
So http://jersey.java.net/ is the Java lib that powers CF10's RESTful web services. Nice to know! Thanks!
However, is there a way to suppress this? In case we don't want to expose some sensitive information that the clients of the API don't need to know about? I don't understand why are the method names exposed, when RESTful API should only cares which action (i.e. GET/PUT/POST/DELETE) are available for certain resource?
remote string function sayOptions() httpMethod="options" {
return "I do x and y";
}
and it worked as expected.