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

4. Just call this function from any cfm.

<cfset restInitApplication("C:\ColdFusion10\cfusion\wwwroot\restApp","IIT")>

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

4. After saving this file go to Administrator --> REST services page
5. In Path text box give the absolute path till directory "restApp". In this example it will be "C:\ColdFusion10\cfusion\wwwroot\restApp"
6. 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
7. 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.