onRestRequest

Last update:

May 18, 2026

Description

The onRestRequest function is an Application.cfc event handler that intercepts any HTTP REST call to a ColdFusion application that exposes RESTful web services. This method provides a centralized location for handling cross-cutting concerns (such as authentication, logging, rate limiting, and dynamic response modifications) before a REST request reaches the targeted CFC method.

Typical use cases include:

Authentication and authorization: Blocking unauthorized or invalid requests.
Request logging: Writing audit trails of all API calls.
API Rate Limiting: Preventing API abuse by limiting requests per client.
Custom error responses or maintenance mode: Returning unified responses during system downtime.
CORS or Header Injection: Dynamically responding with appropriate HTTP headers.

Syntax

function onRestRequest(restRequest) {

    // Custom logic here

}

<cfargument type="struct" name="restRequest" required=false>

Parameters

restRequest: (Struct) A structure containing information about the REST request, including the CFC name, method, arguments, HTTP method, and headers.

Example structure

restRequest = {

   cfcname : "myapi.user",

   method  : "getUser",

   args    : { id="123" },

   httpMethod: "GET",

   headers : { Authorization="Bearer xxxxxx", ... }

};

Returns

Type : any

The method should return the response that you want to send to the REST client. The return value can be any ColdFusion data type (for example, a structure, array, string, or binary data).

Usage

If defined in Application.cfc, it is called on every incoming REST API request before the relevant CFC method is executed.
It enables centralized interception of those requests and optionally alters their flow or output.
To block a request or override normal processing, call restSetResponse() and omit further actions.

Example

Basic logging

component {

    function onRestRequest(restRequest) {

        writeLog(text="REST call: #serializeJSON(restRequest)#", file="rest-access.log");

    }

}

API key authentication

component {

    function onRestRequest(restRequest) {

        var headers = getHttpRequestData().headers;

        if (!structKeyExists(headers, "x-api-key") || headers["x-api-key"] != application.expectedApiKey) {

            restSetResponse({status=401, content="Unauthorized"});

            return false;

        }

    }

}

Rate limiting

component {

    function onRestRequest(restRequest) {

        var ip = cgi.remote_addr;

        if (application.requestTracker[ip] > 100) {

            restSetResponse({status=429, content="Too Many Requests"});

            return false;

        }

        // Increment request count, reset as needed

    }

}

CORS handling

component {

    function onRestRequest(restRequest) {

        var origin = getHttpRequestData().headers["origin"];

        // Allow only from trusted.com

        if (origin == "https://trusted.com") {

            restSetResponse({status=200, headers={"Access-Control-Allow-Origin"=origin}});

        } else {

            restSetResponse({status=403, content="CORS error"});

            return false;

        }

    }

}