Lucee supports REST services allowing developers to expose functionality via HTTP APIs. This guide will help you set up your REST services either by adding the service via the Lucee web/server administrator or by directly defining the service in your application.cfc..
Step-by-step guides in this article:
- Option 1: Add REST Service via Lucee Web/Server Admin
- Option 2: Define the Mapping via Application.cfc
- Creating Components Under the Rest Service
Adding the REST Mapping
There are several ways to add a REST service for your Lucee site. You can add the REST service directly to your Lucee web or server administrator, or you can add the REST service by defining the REST mapping in your application.cfc. The option is entirely up to you. We'll cover both options below:
Option 1: Add REST Service via Lucee Web/Server Admin
You can add the REST service via the Lucee web admin or Lucee server admin, depending on what your preference is and what mode Lucee is running under. If running Lucee in a mulit-context setup, which is often done in a shared environment, then you can add the mapping via the web admin so that it's a site-level service instead of being available to all the sites on the server. If you want the service to be available for all websites on the server, then instead add the REST service via the Lucee server administrator.
The web and server interface should be available at the below paths, be sure to replace the "example.com" section with your actual domain.
Web: http://example.com:8888/lucee/admin/web.cfm
Server: http://example.com:8888/lucee/admin/server.cfm
Note: if you have your website behind a proxy, such as Cloudflare or Sucuri, then you will not be able to hit these URLs by default, since those proxy services will not work with theLucee port, as they only accept port 80 and 443 traffic. Instead, you will need to update your host file for the website to point directly to the server. Please see our guide on updating your hosts file, if needed.
Once logged in to either the web or server admin, follow these steps:
1. Once logged in, click on REST under Archives & Resources.
2. If you have any existing REST mappings set up, then they will be listed here under Mappings. To add a new mapping, fill out the form for Create new mapping:
- Virtual - This should be the relative URL used for the API endpoint, such as
/rest/metricsfor example. - Physical - This should be the physical (not virtual) path on the server that contains the REST api endpoints.
- Default - Usually this should be left unchecked, but when checked, it will act as a "catch-all" for any request matching REST paths and that do not have an explicit mapping configured.
Note: if you want your virtual mapping to not have to include /rest in the URL path, the web server (Apache, Nginx, IIS, etc.) will need to be configured to pass the virtual path to Lucee. Typically, the web server will already be configured to pass all /rest URLs to Lucee so anything custom would need to be added to the web server configuration, which varies for different web servers and the connectors being used to connect the web server to Lucee. If you need assistance with this step we can assist with our SysOps Support.
3. Click Save to save your new mapping.
Option 2: Define the Mapping via Application.cfc
You can add the Lucee mapping via your website's application.cfc by defining the service directly. The example below is from the Lucee guides:
component {
// Application.cfc component
// set a name for the REST application:
this.name = "myRestApplication";
// Define a REST service for the path 'metrics' pointing to the REST application located at
// "C:\path-to-location-with-your-rest-components\" (accessible through http://localhost:8888/rest/metrics/)
restInitApplication(
dirPath="/home/example/public_html/components/metrics/",
serviceMapping="metrics",
password="YourLuceeWebAdministratorPassword"
);
}
Important Note: after definding the REST service within your appication.cfc, you must navigate to a .cfm template in your browser to first invoke the Application.cfc above. Not doing so will result in a missing REST mapping. Also, you will want to make sure that you are entering the correct password in the application. If doing this option worries you, then you may want to do Option 1 instead, where the service is defined in the Lucee context instead of your code.
Creating Components Under the REST Service
The above sections walk you through creating the REST service mapping(s). Those service mappings will need to point to the folder on the server that contains the components those services depend on. Under the REST component path, create the necessary CFC files that define your REST methods, such as the example below:
// System.cfc
/**
* @hint returns server operating system by accessing the path /rest/mappedRESTServiceName/system/os
*/
remote struct function getOS() httpmethod="GET" restpath="os" {
return server.os;
}
/**
* @hint returns specific timezone struct values by passing the timezones struct key name
* with the path /rest/mappedRESTServiceName/system/timezone/{timezone-struct-keyName}
* e.g. /rest/mappedRESTServiceName/system/timezone/name
* or /rest/mappedRESTServiceName/system/timezone/id
*/
remote string function getTimeZone(
required string key restargsource="Path",
string locale="en_US" restargsource="url")
httpmethod="GET" restpath="timezone/{key}" {
setLocale(arguments.locale);
var tzInfo=getTimeZoneInfo();
return tzInfo[arguments.key];
}
}
The above, also taken from the Lucee guides, show an example of adding a system compontent that has two GET methods. The first method returns information about the server OS while the second method returns information about the timezone.
Below are a few example URL requests you can make with this REST service.
http://example.com/rest/metrics/system/os http://example.com/rest/metrics/system/timezone/name http://example.com/rest/metrics/system/timezone/id http://example.com/rest/metrics/system/timezone/name?locale=pt_BR http://example.com/rest/metrics/system/timezone/name?locale=zh_TW http://example.com/rest/metrics/system/timezone/utcHourOffset
More Help and Resources
Additional information is available within Lucee's documentation. Some of the same information and examples that we've covered can be found there as well as some additional information on how to use different functions within your REST components.
If you're encountering any issues that you would like our team to help investigate, we'd be happy to assist you via our SysOps Support. Let us know how we can help!