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:
Archived Comments
Not related to the topic, but I've always wanted to ask: Why do you use new com.adobe.coldfusion.query() instead of just new query()?
Wow!
Thanks for examples
I use the full domain in case the default custom tag directory doesn't exist. Plus, I prefer using the full path for things outside of my app. It "feels" safer.
Cool! You're welcome Ray.
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?
Yes. I added this:
remote string function sayOptions() httpMethod="options" {
return "I do x and y";
}
and it worked as expected.
This is interesting, and can be helpful. Give that this self-description is possible does anyone know if Adobe plans to implement a WADL description page similar to the ?wsdl and ?wsdl2
Are you asking if we will add a 'url hook' to return it? I don't think that is necessary if you can simply send an OPTIONS request. I'm still new to REST, but in general, the idea is to use HTTP Verbs, not URL params, to get stuff.
I noticed that neither the displayName or hint attributes of the cfargument tag translate to <doc> elements in the WADL. Any plans to add this?
No idea. :) Please file an ER for this.
Hi Ray,
I'm working on a RESTful API for our company but can't quite figure out how to get it to work with IIS 7.5. I'd like the services to be accessible over port 80 on their website domain (say http://api.company.com)... Are there any good demos/tutorials/examples that you have seen to make this work with IIS, not just localhost:8500?
JJ
There isn't any docs because it should just work. If your CF server is tied to IIS, then it just works. (Or it should.)
Well, it's returning a string 'Not Found' in the browser - no HTML wrapped around, just those two words. When I look in the error logs, I see this error:
"Error","ajp-bio-8012-exec-3","05/19/13","14:26:15",,"File not found: /websocket/adc/v1/helloWorld.cfm The specific sequence of files included or processed is: C:\inetpub\wwwroot\perkz2\websocket\adc\v1\helloWorld.cfm'' "
coldfusion.runtime.TemplateNotFoundException: File not found: /websocket/adc/v1/helloWorld.cfm
I put the CFC in its own folder in my intetpub\wwwroot\api\ folder with an fairly empty application.cfc...
Have you seen this error before?
I apologize, that is not the error I was getting... that is an old one... Here is the error I'm getting:
"Error","ajp-bio-8012-exec-7","07/12/13","16:32:43",,"null for uri: http://api.perkz.biz/rest/s..."
com.sun.jersey.api.NotFoundException: null for uri: http://api.perkz.biz/rest/s...
Hmm. Not sure. For Apache I had to ensure I had the right stuff set up. Maybe try running your connector again.
Hello,
Is it possible to set the default return format for the OPTIONS verb to json instead of xml?
Thanks!
My understanding is that the spec says to return XML.