ColdFusion 10 REST and Self-Documentation

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:

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:

Raymond Camden's Picture

About Raymond Camden

Raymond is a senior developer evangelist for Adobe. He focuses on document services, JavaScript, and enterprise cat demos. If you like this article, please consider visiting my Amazon Wishlist or donating via PayPal to show your support. You can even buy me a coffee!

Lafayette, LA https://www.raymondcamden.com

Archived Comments

Comment 1 by RHPT posted on 12/6/2012 at 8:16 PM

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()?

Comment 2 by inj posted on 12/6/2012 at 8:18 PM

Wow!
Thanks for examples

Comment 3 by Raymond Camden posted on 12/7/2012 at 1:21 AM

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.

Comment 4 by Henry Ho posted on 12/7/2012 at 1:30 AM

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?

Comment 5 by Raymond Camden posted on 12/7/2012 at 1:36 AM

Yes. I added this:

remote string function sayOptions() httpMethod="options" {
return "I do x and y";
}

and it worked as expected.

Comment 6 by John posted on 12/20/2012 at 3:58 AM

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

Comment 7 by Raymond Camden posted on 12/20/2012 at 6:46 AM

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.

Comment 8 by John posted on 2/21/2013 at 10:01 PM

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?

Comment 9 by Raymond Camden posted on 2/21/2013 at 11:10 PM

No idea. :) Please file an ER for this.

Comment 10 by John Jarrard posted on 7/12/2013 at 7:44 AM

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

Comment 11 by Raymond Camden posted on 7/12/2013 at 3:45 PM

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.)

Comment 12 by John Jarrard posted on 7/13/2013 at 12:36 AM

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?

Comment 13 by John Jarrard posted on 7/13/2013 at 12:40 AM

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...

Comment 14 by Raymond Camden posted on 7/13/2013 at 1:39 AM

Hmm. Not sure. For Apache I had to ensure I had the right stuff set up. Maybe try running your connector again.

Comment 15 by Scott Kroyer posted on 1/4/2014 at 10:54 PM

Hello,

Is it possible to set the default return format for the OPTIONS verb to json instead of xml?

Thanks!

Comment 16 by Raymond Camden posted on 1/6/2014 at 4:19 AM

My understanding is that the spec says to return XML.