Lucee RESTful Webservice Tutorial
This tutorial will go over the steps for setting up a RESTful webservice using Lucee.
Overview
All rest requests use one of the following special path formats:
/rest/APPLICATION/COMPONENT /rest/APPLICATION/COMPONENT/FUNCTION
For the Default rest application, the following mappings are used. The default rest application is assigned within the Lucee Web Administrator:
/rest/COMPONENT /rest/COMPONENT/FUNCTION
- APPLICATION: The virtual path assigned to the application in the Lucee Web Administrator.
- COMPONENT: The name of the cfcomponent or the restpath of the component if one is provided.
- FUNCTION: The restpath of the cffunction if one is provided.
For functions that do not have a restpath, the specific function executed depends on the http verb(I.E. get,put,post,delete) matching the httpMethod property of the function.
Create webservice files
The webservice files should be added to a sub-folder within your site. The webservice will be comprised of a group of .cfc files with the rest parameter on the cfcomponent tag set to true. You can also use the restpath parameter to specify the path that should be used for each component if you do not want to use the default of the component name. Each method also accepts a restpath parameter if you wish the method to use a sub-path under the component. Here is an example service:
<cfcomponent rest="true" restpath="/restexample">
<cffunction name="greeting" access="remote" returnType="string" httpMethod="get">
<cfreturn "{ ""Lucee"": ""I'm home!"" }">
</cffunction>
</cfcomponent>
Add webservice mapping
- Log into the Lucee Web Administrator
- Select Archives and Resources -> Rest
- Enter the following details within the Create new mapping section:
- Virtual: The APPLICATION path that you will use when accessing the rest application.
- Physical: The site-relative path to the directory containing the rest cfc components.
- Default: The default rest application can be accessed without including the a APPLICATION portion in the url.
- Click save
Add handler mapping
Since the rest URLs will not end with a normal cfml file extension, we will need to manually tell IIS that we want URLs under the rest path to be sent to Lucee for processing. This is done by adding a handler to the web.config within the site's webroot(/wwwroot). Below is an example of how we could add a rest mapping for the example component given previously:
</configuration>
</system.webServer>
<handlers>
<add name="BonCode-Tomcat-REST-Handler-restexample" path="/rest/restexample/*" verb="*" type="BonCodeIIS.BonCodeCallHandler,BonCodeIIS,Version=1.0.0.0,Culture=neutral,PublicKeyToken=ad590a40d40745cf" resourceType="Unspecified" preCondition="integratedMode" />
</handlers>
</system.webServer>
</configuration>
Here is another example that we would use if we chose the Default option when adding the rest mapping in the Lucee Web Administrator:
</configuration>
</system.webServer>
<handlers>
<add name="BonCode-Tomcat-REST-Handler-default" path="/rest/*" verb="*" type="BonCodeIIS.BonCodeCallHandler,BonCodeIIS,Version=1.0.0.0,Culture=neutral,PublicKeyToken=ad590a40d40745cf" resourceType="Unspecified" preCondition="integratedMode" />
</handlers>
</system.webServer>
</configuration>