Tuesday 21 February 2012

Getting Started with REST in ColdFusion 10



<- Previous Contents Next ->



PART-I

Tutorial on REST: Getting Started:

Background: REST services are a kind of web services which use http protocol behind the scenes. Geeks familiar with SOAP based web services must be thinking, Is this really possible (if they don't already know about REST architecture yet)? Yes, REST services uses HTTP architecture to get the work done and same way ColdFusion10 has beautifully used its component(cfc) to publish the REST services and cfhttp tags to consume them. For more information on REST architecture please go through this link.

Note - for simpler understanding, throughout the tutorial I will consider that ColdFusion is installed at "C:\ColdFusion10\" with webroot at "C:\ColdFusion10\cfusion\wwwroot\" and is running on port "8500".

Publishing
  1. After installing ColdFusion10 and setting the webroot(either through standalone or using webserver like IIS or Apache), first step required to setup REST is write a REST enabled cfc in some folder in webroot.
  2. Create a directory named "restApp" in webroot of ColdFusion. You can name this directory whatever you want to as this is just for your reference.
  3. Create a cfc named as "studentHandler.cfc". You can name this cfc as anything you want. Your REST service users will not use this name untill and unless you are mentioning "restpath" at component level in your cfc. I will come to this point later
Paste code given below in this studentHandler.cfc



For those who prefers to stay independent of Administrator
  1. Just call this function from any cfm.
<cfset restInitApplication("C:\ColdFusion10\cfusion\wwwroot\restApp","IIT")>
  1. First argument to "restInitApplication" function is the absolute path where you have placed your REST component(studentHandler.cfc) and second argument is the name from which you will publish your REST application. You can give your relevant Organization name in second argument.
  2. If you didn't got any error after running this funtion, it means your application is registered successfully. That's it, first REST application published.


For those who prefers to use ColdFusion Administrator page (http://127.0.0.1/8500/CFIDE/administrator/index.cfm)
  1. After saving this file go to Administrator --> REST services page
  2. In Path text box give the absolute path till directory "restApp". In this example it will be "C:\ColdFusion10\cfusion\wwwroot\restApp"
  3. In mapping text box give some logical name for the REST application you going to create, let's say "IIT". You can give your relevant Organization name. This name will be used by users in the URL
  4. Hit register, and there you go. First REST application published.

Behind the scenes/tricks:
(these are quick tricks to know, but will covered in later parts of tutorial)
  1. When you hit 'restInitApplication()' function, ColdFusion registers your application. You can also see that application later on in Administrator REST Services page.
  2. When you create a REST enabled component in your webroot and register that folder, ColdFusion consider that folder as one REST application. 
  3. As many resources(cfc or functions in cfc) as you want, can be created in one application but the only thing is that restpath for these resources should not conflict with each other.
  4. Nested REST applications are not allowed.
  5. You can keep your application outside webroot too. For this you need to add a mapping for a directory in Administrator and then you can register this directory using absolute path or mapping(the name with which you added a mapping), both will work. 
  6. Application names are case-INsensitive.
  7. Calling restInitApplication() for already registered application actually REFRESH that application.
  8. Calling restInitApplication() with different mapping name(second attribute) will update the registered application with absolute path(first argument), with new name.
  9. If you want to skip giving application mapping name, you can use 'default' feature, you can set an application as default and while consuming you can call a resource without giving mapping name in URL. Keep checking  this area for this point. I will write separate post for this.
  10. While registering an application, if application mapping name is not given, then it picks the same in the directory's(one you are trying to register) Application.cfc(this.name).




Consuming


As you saw it was damn easy to publish a REST service but consuming is a lot Easier than that. All you need to do is hit this URL: http://127.0.0.1:8500/rest/IIT/student

I hope you got the response as "foo", because this is what we returned from studentHandler.cfc in function "getMethod".

How URL works:

  1. http://127.0.0.1:8500/ - This is a equivalent to protocol://ip:port of your server in which the REST resource is present.
  2. /rest/ - This string 'rest' in URL is necessary to tell ColdFusion that this is a REST call. You can change this 'rest' in server.xml
  3. /IIT/ - this is the mapping_name from which you registered your REST application.
  4. /student/ - This is the restpath of the resource you defined in studentHandler.cfc
Consuming in cfm:
  1. For consuming REST services in cfm file you need to call the above URL using cfhttp tag.
  2. Run the code given below.
  3. Just take care that the method in cfhttp call should be 'get', as it has to match the 'httpmethod' given in cfc.

How this works
  1. By looking at the URL, ColdFusion gets to know that this is a REST call and it also gets to know that for which application this call has been made because of the mapping name present in URL('IIT' in this example)
  2. Once we know that which application it is, we can easily get to know that which resource(cfc) has been called, because a cfc has a restpath which has to be unique for every appliction and this restpath is also included in URL('student' in this example)
  3. Once we get to know that which cfc has been called, we match the httpmethod of cffunction with the method of the request(cfhttp). In this example for both of them we mentioned 'GET'. So by calling a get request on this resource we hit the function whose httpmethod is 'get'.
  4. Once we know which cffunction to call, its very easy to return the response.
  5. There is also a possibility to have more than one function in same resource with different httpmethod, So it's quite possible that on calling same URL with get request you might hit one function whereas calling 'put' you might hit another. Details about this will be covered later.

Note:Application name(mapping name from which you registered your REST app) is case IN-sensitive.

<- Previous Contents Next ->



Thanks,
Milan.

25 comments:

  1. Hello Milan,
    I'm working on CF10,IIS 7.5, Windows7 64.
    Under IIS I created some virtual hosts.
    I tried to register REST services specifying the absolute path (which is under a virtual host dierectory outside IIS inetpub/wwwroot) but I receive every time the "Reason: The application does not contain any rest enabled CFCs" error.
    The same folder is regetered well if I move it under the inetpub/wwwroot.
    Cause to the cross domain restrictions I can't test the virtual host site (which use JQuery ajax calls) referencing a CF10 REST service under the inetpub/wwwroot.
    I tryied to map the folder as you indicate ("Behind the scenes/tricks" - 5) anyway the directory wasn't registered by CF10.
    Is there a way to work in this scenario ?
    Thank you

    ReplyDelete
    Replies
    1. Hi,
      Well that trick should work.
      Can you try one thing.
      After creating a mapping for external folder,
      Try to create an object of that CFC or try to invoke that CFC using mapped folder name.
      That will tell if the folder is properly mapped or not.
      If it is mapped, then while registering REST, either give absolute path or mapped path in "Root path", both should work.

      Delete



  2. Hi, Great.. Tutorial is just awesome..It is really helpful for a newbie like me.. I am a regular follower of your blog. Really very informative post you shared here. Kindly keep blogging. If anyone wants to become a Front end developer learn from Node JS Online Training from India . or learn thru Javascript Online Training from India. Nowadays JavaScript has tons of job opportunities on various vertical industry. ES6 Online Training

    ReplyDelete
  3. Can this work for ColdFusion 9?

    ReplyDelete
  4. Whoa! I’m enjoying the template/theme of this website. It’s simple, yet effective. A lot of times it’s very hard to get that “perfect balance” between superb usability and visual appeal. I must say you’ve done a very good job with this.

    AWS TRAINING IN BTM LAYOUT | AWS TRAINING IN BANGALORE
    AWS Training in Marathahalli | AWS Training in Bangalore

    ReplyDelete
  5. This is a good post. This post give truly quality information. I’m definitely going to look into it. Really very useful tips are provided here. thank you so much. Keep up the good works.
    online Python training
    python training in chennai

    ReplyDelete
  6. I think this is the best article today about the future technology. Thanks for taking your own time to discuss this topic, I feel happy about that curiosity has increased to learn more about this topic.Artificial Intelligence Training in Bangalore. Keep sharing your information regularly for my future reference.

    ReplyDelete
  7. Awesome article. It is so detailed and well formatted that i enjoyed reading it as well as get some new information too.
    AWS Training in Bangalore
    AWS training in sholinganallur
    AWS training in Tambaram
    AWS training in Velachery

    ReplyDelete
  8. This information is impressive; I am inspired with your post writing style & how continuously you describe this topic. After reading your post, thanks for taking the time to discuss this, I feel happy about it and I love learning more about this topic.
    oneplus service centre
    oneplus mobile service center in chennai

    ReplyDelete
  9. Thanks for excellent article. Moving Men Removals is the renowned local removalists Melbourne.

    ReplyDelete
  10. This comment has been removed by the author.

    ReplyDelete
  11. Great blog thanks for sharing Instagram and Facebook have provided an amazing place for new brands to grow and flourish. We can find the perfect niche for your brand on the best social media platforms. Marketing through social media brings forth global audience without all these physical boundaries.
    seo service in chennai

    ReplyDelete
  12. Nice blog thanks for sharing Tidy up your ambience by decorating them with amazing landscape plants in Chennai. Karuna Nursery Gardens is your portal to all the green that the world has to offer. Revolutionize your indoors, garden, terrace or office right now with us.
    corporate gardening service in chennai

    ReplyDelete
  13. Thanks for posting the valuable information's the Blogs contains a much needed information's to enhance the knowledge..Thanks for sharing

    python training in chennai | python training in annanagar | python training in omr | python training in porur | python training in tambaram | python training in velachery

    ReplyDelete
  14. Thanks for posting the valuable information's the Blogs contains a much needed information's to enhance the knowledge..Thanks for sharing

    AWS training in Chennai

    AWS Online Training in Chennai

    AWS training in Bangalore

    AWS training in Hyderabad

    AWS training in Coimbatore

    AWS training

    ReplyDelete
  15. Thanks for sharing the best information and suggestions, I love your content, and they are very nice and very useful to us. If you are looking for the best Pest Control Hawthorn, then visit Pest Control Hawthorn. I appreciate the work you have put into this. Fumigation Melbourne

    ReplyDelete
  16. Nice article, its very informative content..thanks for sharing...Waiting for the next update.

    best language for app development
    best programming language for mobile apps

    ReplyDelete
  17. Nice article, its very informative content..thanks for sharing...Waiting for the next update.
    react native vs flutter
    flutter vs react

    ReplyDelete

  18. Infycle offers the solitary AWS training in Chennai for the freshers, professionals, and students along with the additional course such as DevOps Training and Java training for making the candidate an all-rounder in the Software domain field. For a lucrative career, dial 7504633633, 7502633633.

    ReplyDelete