6.x
Docs
Source
Support
Training

REST Handler

ColdBox supports native REST handling via the RestHandler and native routing.

RestHandler & ColdBox Response

ColdBox 6 has native REST capabilities alongside the RestHandler and a customizable Response object into the core. This RestHandler will provide you with utilities and approaches to make all of your RESTFul services:

  • Uniformity on Responses

  • A consistent and extensible response object

  • Consistent Error handling

  • Invalid route handling

  • Internal Events

  • Much more

In previous versions of ColdBox support for RESTful services was provided by adding the base handler and the response object to our application templates. Integration into the core brings ease of use, faster handling and above all: a uniform approach for each ColdBox version in the future.

Base Class: RestHandler

For the creation of REST handlers you can inherit from our base class coldbox.system.RestHandler, directly via extends="coldbox.system.Resthandler" or our using the restHandler annotation.

This will give you access to our enhanced API of utilities and the native response object via the request context's getResponse() method.

component extends="coldbox.system.RestHandler"{

  function index( event, rc, prc ){
    event.getResponse()
      .setData( "Hello from restful Land" );
  }
}

component resthandler{

  function index( event, rc, prc ){
    event.getResponse()
      .setData( "Hello from restful Land" );
  }

}

You will then leverage that response object (https://apidocs.ortussolutions.com/coldbox/current/index.html?coldbox/system/web/context/Response.html) to do the following actions:

  • Set the data to be converted to JSON, XML or whatever

  • Set pagination data

  • Set errors

  • Set if the data is binary or not

  • Set location headers

  • Set message arrays

  • Set json call backs

  • Set json query formats

  • Set response contentType

  • Set response statusCode

  • Set response headers

  • Much More

Upgrade Pointers: The response object will be accessible using the event.getResponse() method but will still be available as prc.response.

If you are using cbORM make sure to check the chapter Automatic Rest Crud

Base Rest Handler Actions

The Rest handler gives you the following actions coded for you out of the box. You can override them if you want, but the idea is that this base takes you a very long way.

Core Actions

Purpose

aroundHandler()

Wraps all rest actions uniformly to provide consistency and error trapping.

onError()

An implicit error handler is provided just in case anything explodes in your restful actions. Sends an appropriate 500 error

onValidationException()

Traps any and makes sure it sends the appropriate 400 response with the invalid data. Useful for using cbValidation, for example with the validateOrFail() methods.

onEntityNotFoundException()

Traps any or exceptions and makes sure it send an appropriate 404 response. Useful for leveraging cborm or Quick ORM

onInvalidHTTPMethod()

Traps any invalid HTTP method security exception and sends the appropriate 405 not allowed response

onMissingAction()

Traps any invalid actions/resource called in your application and sends the appropriate 404 response

onAuthenticationFailure()

Traps InvalidCredentials exceptions and sends the appropriate 403 invalid credentials response. If you are using cbSecurity it will also verify jwt token expiration and change the error messages accordingly.

onAuthorizationFailure()

Traps PermissionDenied exceptions and sends the appropriate 401 response. This Action can be used when a user does not have authorization or access to your application or code. Usually you will call this manually or from a security library like cbSecurity or cbGuard. It will send a 401 not authorized response.

onInvalidRoute()

Action that can be used as a catch all from your router so it can catch all routes that are invalid. It will send a 404 response accordingly.

onExpectationFailed()

Utility method for when an expectation of the request fails ( e.g. an expected parameter is not provided ). This action is called manually from your own handlers and it will output a 417 response back to the user.

onAnyOtherException

Fires when ANY exception that is not excplicitly trapped is detected. This basically logs the issue and offers a 500 error. You can now intercept it and do whatever you need on ANY type of untrapped exception.

AroundHandler in Detail

The aroundHandler() provided in the RestHandler will intercept all rest calls in order to provide consistency and uniformity to all your actions. It will try/catch for major known exceptions, time your requests, add extra output on development and much more. Here are a list of the features available to you:

Exception Handling

Automatic trapping of the following exceptions:

  • EntityNotFound

  • InvalidCredentials

  • PermissionDenied

  • RecordNotFound

  • TokenInvalidException

  • ValidationException

If the trapped exception is not one from above, then we will call the onAnyOtherException() action. This action will log automatically the exception with extra restful metadata according to the environment you are executing the action with. It will also setup an exception response for you.

If in a development environment it will respond with much more information necessary for debugging both in the response object and headers

Development Responses

If you are in a development environment it will set the following headers for you in the response object automatically.

  • x-current-event

  • x-current-route

  • x-current-routed-url

  • x-current-routed-namespace

Global Headers

The following headers are sent in each request no matter the environment:

  • x-response-time : The time the request took in CF

  • x-cached-response : If the request is cached via event caching

Output Detection

The aroundHandler() is also smart in detecting the following outputs from a handler, which will ignore the REST response object:

  • Handler return results

  • Setting a view or layout to render

  • Explicit renderData() calls

Rest Handler Security

The RestHandler also gives you HTTP method security out of the box by convention based on ColdBox resources. The following is already created for you using the this.allowedMethods structure:

// Default REST Security for ColdBox Resources
this.allowedMethods = {
	"index"  : "GET",
	"new"    : "GET",
	"get"    : "GET",
	"create" : "POST",
	"show"   : "GET",
	"list"   : "GET",
	"edit"   : "GET",
	"update" : "POST,PUT,PATCH",
	"delete" : "DELETE"
};

Also note that since this is a base class, you can override this structure or append to it as you see fit.

Response Object

The Response object is used by the developer to set into it what the response will be by the API call. The object is located at coldbox.system.web.context.Response and can be retrieved by the request context object's getResponse() method.

Response Format

Every response is created from the internal properties in the following JSON representation:

{
  "error"      : getError() ? true : false,
  "messages"   : getMessages(),
  "data"       : getData(),
  "pagination" : getPagination()
};

You can change this response by extending the response object and doing whatever you want.

Properties

The Response object has the following properties you can use via their getters and setter methods.

PropertyTypeDefaultUsage

binary

boolean

false

If the data property is binary

contentType

string

---

Custom content type of the response

data

struct

---

The data struct marshalled in the response

error

boolean

false

Boolean bit denoting an exception or problem in the API call

format

string

json

The response format of the API. Defaults to json.

jsonCallback

string

---

If using a callback then set the callback method here.

jsonQueryFormat

string

true

This parameter can be a Boolean value that specifies how to serialize ColdFusion queries or a string with possible values row, column, or struct

location

string

---

The location header to send with the response

messages

array

---

Array of messages to send in the response packet

pagination

struct

{ offset, maxRows, page, totalRecords, totalPages }

A pagination struct to return

responseTime

numeric

0

The time the request and response took

statusCode

numeric

200

The status code to send

statusText

string

OK

The status text to send

Convenience Methods

A part from the setters/getters from the properties above, the response object has some cool convenience methods:

/**
 * Utility function to get the state of this object
 */
struct function getMemento()

/**
 * Add some messages to the response
 *
 * @message Array or string of message to incorporate
 */
Response function addMessage( required any message )

/**
 * Get all messages as a string
 */
string function getMessagesString()

/**
 * Add a header into the response
 *
 * @name  The header name ( e.g. "Content-Type" )
 * @value The header value ( e.g. "application/json" )
 */
Response function addHeader( required string name, required string value )

/**
 * Set the pagination data
 *
 * @offset       The offset
 * @maxRows      The max rows returned
 * @page         The page number
 * @totalRecords The total records found
 * @totalPages   The total pages found
 */
Response function setPagination(
	numeric offset       = 0,
	numeric maxRows      = 0,
	numeric page         = 1,
	numeric totalRecords = 0,
	numeric totalPages   = 1
)

/**
 * Returns a standard response formatted data packet using the information in the response
 *
 * @reset Reset the 'data' element of the original data packet
 */
struct function getDataPacket( boolean reset = false )

/**
 * Sets the status code with a statusText for the API response
 *
 * @code The status code to be set
 * @text The status text to be set
 *
 * @return Returns the Response object for chaining
 */
Response function setStatus( required code, text )

/**
 * Sets the data and pagination from a struct with `results` and `pagination`.
 *
 * @data          The struct containing both results and pagination.
 * @resultsKey    The name of the key with the results.
 * @paginationKey The name of the key with the pagination.
 *
 * @return Returns the Response object for chaining
 */
Response function setDataWithPagination(
	data,
	resultsKey    = "results",
	paginationKey = "pagination"
)

/**
 * Sets the error message with a code for the API response
 *
 * @errorMessage The error message to set
 * @statusCode   The status code to set, if any
 * @statusText   The status text to set, if any
 *
 * @return Returns the Response object for chaining
 */
Response function setErrorMessage(
	required errorMessage,
	statusCode,
	statusText = ""
)}

Status Text Lookup

The response object also has as STATUS_TEXTS public struct exposed so you can use it for easy status text lookups:

this.STATUS_TEXTS = {
    "100" : "Continue",
    "101" : "Switching Protocols",
    "102" : "Processing",
    "200" : "OK",
    "201" : "Created",
    "202" : "Accepted",
    "203" : "Non-authoritative Information",
    "204" : "No Content",
    "205" : "Reset Content",
    "206" : "Partial Content",
    "207" : "Multi-Status",
    "208" : "Already Reported",
    "226" : "IM Used",
    "300" : "Multiple Choices",
    "301" : "Moved Permanently",
    "302" : "Found",
    "303" : "See Other",
    "304" : "Not Modified",
    "305" : "Use Proxy",
    "307" : "Temporary Redirect",
    "308" : "Permanent Redirect",
    "400" : "Bad Request",
    "401" : "Unauthorized",
    "402" : "Payment Required",
    "403" : "Forbidden",
    "404" : "Not Found",
    "405" : "Method Not Allowed",
    "406" : "Not Acceptable",
    "407" : "Proxy Authentication Required",
    "408" : "Request Timeout",
    "409" : "Conflict",
    "410" : "Gone",
    "411" : "Length Required",
    "412" : "Precondition Failed",
    "413" : "Payload Too Large",
    "414" : "Request-URI Too Long",
    "415" : "Unsupported Media Type",
    "416" : "Requested Range Not Satisfiable",
    "417" : "Expectation Failed",
    "418" : "I'm a teapot",
    "421" : "Misdirected Request",
    "422" : "Unprocessable Entity",
    "423" : "Locked",
    "424" : "Failed Dependency",
    "426" : "Upgrade Required",
    "428" : "Precondition Required",
    "429" : "Too Many Requests",
    "431" : "Request Header Fields Too Large",
    "444" : "Connection Closed Without Response",
    "451" : "Unavailable For Legal Reasons",
    "499" : "Client Closed Request",
    "500" : "Internal Server Error",
    "501" : "Not Implemented",
    "502" : "Bad Gateway",
    "503" : "Service Unavailable",
    "504" : "Gateway Timeout",
    "505" : "HTTP Version Not Supported",
    "506" : "Variant Also Negotiates",
    "507" : "Insufficient Storage",
    "508" : "Loop Detected",
    "510" : "Not Extended",
    "511" : "Network Authentication Required",
    "599" : "Network Connect Timeout Error"
};

Extending The RestHandler

If you would like to extend or modify the behavior of the core RestHandler then you will have to create your own base handler that inherits from it. Then all of your concrete handlers will inherit from your very own handler.

// BaseHandler
component extends="coldbox.system.Resthandler"{

  // Modify it here

}

// Then make your own handlers extend from it
component extends="BaseHandler"{

}

Extending The Response Object

The response object can be found here: coldbox.system.web.context.Response and the rest handler constructs it by calling the request context’s getResponse() method. The method verifies if there is a prc.response object and if it exists it returns it, else it creates a new one. So if you would like to use your very own, then just make sure that before the request you place your own response object in the prc scope.

Here is a simple example using a preProcess() interceptor. Create a simple interceptor with commandbox e.g

coldbox create interceptor name=MyInterceptor points=preProcess

and add the following method:

function preProcess( event, interceptData, rc, prc ){
  prc.response = wirebox.getInstance( "MyResponseObject" );
}

Don't forget to register your interceptor in config/Coldbox.cfc:

        interceptors = [
            {
            class      : "interceptors.MyInterceptor",
                name       : "MyInterceptor",
                properties : {}
            }
        ];

That’s it. Once that response object is in the prc scope, ColdBox will utilize it. Just make sure that your custom Response object satisfies the methods in the core one. If you want to modify the output of the response object a good place to do that would be in the getDataPacket() method of your own MyResponseObject. Just make sure this method will return a struct.

Last updated