Twitter: raymondcamden


Address: Lafayette, LA, USA

ColdFusion 10 REST and Self-Documentation

12-06-2012 5,999 views ColdFusion 16 Comments

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:

16 Comments

  • RHPT #
    Commented on 12-06-2012 at 9:16 AM
    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()?
  • Commented on 12-06-2012 at 9:18 AM
    Wow!
    Thanks for examples
  • Commented on 12-06-2012 at 2:21 PM
    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.
  • Commented on 12-06-2012 at 2:30 PM
    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?
  • Commented on 12-06-2012 at 2:36 PM
    Yes. I added this:

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

    and it worked as expected.
  • John #
    Commented on 12-19-2012 at 4:58 PM
    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
  • Commented on 12-19-2012 at 7:46 PM
    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.
  • John #
    Commented on 02-21-2013 at 11:01 AM
    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?
  • Commented on 02-21-2013 at 12:10 PM
    No idea. :) Please file an ER for this.
  • John Jarrard #
    Commented on 07-11-2013 at 10:44 PM
    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
  • Commented on 07-12-2013 at 6:45 AM
    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.)
  • John Jarrard #
    Commented on 07-12-2013 at 3:36 PM
    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?
  • John Jarrard #
    Commented on 07-12-2013 at 3:40 PM
    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/sayhello/"
    com.sun.jersey.api.NotFoundException: null for uri: http://api.perkz.biz/rest/sayhello/
  • Commented on 07-12-2013 at 4:39 PM
    Hmm. Not sure. For Apache I had to ensure I had the right stuff set up. Maybe try running your connector again.
  • Commented on 01-04-2014 at 11:54 AM
    Hello,

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

    Thanks!
  • Commented on 01-05-2014 at 5:19 PM
    My understanding is that the spec says to return XML.

Post Reply

Please refrain from posting large blocks of code as a comment. Use Pastebin or Gists instead. Text wrapped in asterisks (*) will be bold and text wrapped in underscores (_) will be italicized.

Leave this field empty