Experimenting With RESTful Error Response Codes And CFThrow's ErrorCode Attribute

<!---
	For this demo, we are only going to deal with a single
	"resource" that accepts NAME and AGE values. We don't want to
	param them here so that we can return more granular data in
	the error response.

	param url.name
	param url.age
--->


<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->


<!---
	Set up some default values in the request. This data will help
	us determine what kind of response we ultimately want to return
	to the client.
--->

<!---
	The status code will mimic the HTTP status code (in case the
	status code is being suppressed for clients that can't handle
	non-200 responses.
--->
<cfset request.statusCode = 200 />
<cfset request.statusText = "OK" />

<!---
	The Response key is the resource payload being returned from the
	API. This is the ONLY KEY that will be OVERRIDDEN directly by the
	resource handlers. Every other key will be set by the primary
	RESTful controller.
--->
<cfset request.response = true />

<!---
	This is the error code and message for any errors that occurred
	during the API request.
--->
<cfset request.errorCode = 0 />
<cfset request.errorText = "" />
<cfset request.errorDetail = "" />


<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->


<!---
	Because there are only a small number (relavitely speaking) of
	generic HTTP status codes, we want to be able to provide more
	insightful error codes that are relevant to our RESTful API. Each
	error response should include one of the following values that
	the 3rd party API developer can use when interacting with and
	debugging their API responses.
--->
<cfset request.errorCodes = {} />
<cfset request.errorCodes[ "10000" ] = "Unexpected error." />
<cfset request.errorCodes[ "11011" ] = "Name is missing." />
<cfset request.errorCodes[ "11012" ] = "Name is invalid." />
<cfset request.errorCodes[ "11021" ] = "Age is missing." />
<cfset request.errorCodes[ "11022" ] = "Age is invalid." />


<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->


<!---
	While processing the API request, we any number of things could
	go wrong - both expected and unexpected. As such, we'll wrap all
	processing in a Try/Catch block so that we can intercept errors
	and turn them into appropriate RESTful error response values.

	NOTE: Custom errors (via CFThrow) must include an [errorCode]
	attribute so that the error responses can be constructed properly.
--->
<cftry>

	<!---
		Include the resource processing controller. Imagine that
		this routes to one of many possible resources (even though
		this demo only has ONE resource to process).
	--->
	<!--- ------------------------------------------------- --->
	<!--- ------------------------------------------------- --->
	<cfinclude template="process.cfm" />
	<!--- ------------------------------------------------- --->
	<!--- ------------------------------------------------- --->


	<!--- Catch bad request errors. --->
	<cfcatch type="BadRequest">

		<!---
			Set up the error data. Notice that we are using the
			errorCode in the CFCatch exception to provide more
			insight into the error.
		--->
		<cfset request.statusCode = 400 />
		<cfset request.statusText = "Bad Request" />
		<cfset request.errorCode = cfcatch.errorCode />
		<cfset request.errorText = request.errorCodes[ cfcatch.errorCode ] />
		<cfset request.errorDetail = cfcatch.message />

	</cfcatch>

	<!--- Catch any unexpected errors. --->
	<cfcatch>

		<!--- Set up the error data. --->
		<cfset request.errorCode = 10000 />
		<cfset request.errorText = request.errorCodes[ "100000" ] />
		<cfset request.errorDetail = cfcatch.message />

	</cfcatch>

</cftry>


<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->


<!--- Set the response headers. --->
<cfheader
	statuscode="#request.statusCode#"
	statustext="#request.statusText#"
	/>

<!---
	Check to see if any errors were raised during the request
	processing. If so, we need to override the response value with
	an error response.
--->
<cfif request.errorCode>

	<!--- There was an error. Create an error object. --->
	<cfset request.response = {} />
	<cfset request.response[ "statusCode" ] = request.statusCode />
	<cfset request.response[ "errorCode" ] = request.errorCode />
	<cfset request.response[ "errorText" ] = request.errorText />
	<cfset request.response[ "errorDetail" ] = request.errorDetail />
	<cfset request.response[ "resource" ] = cgi.script_name />
	<cfset request.response[ "verb" ] = cgi.request_method />

</cfif>

<!--- Serialize the response. --->
<cfset serializedResponse = serializeJSON( request.response ) />

<!---
	Stream response to the client as a JSON body.

	NOTE: We are using "text/plain" rather than "application/json"
	so that we can more easily render the response in the browser
	for the demo.
--->
<cfcontent
	type="text/plain"
	variable="#toBinary( toBase64( serializedResponse ) )#"
	/>

<!---
	Resource expects:

	name: String
	age: Numeric (0 - 99)
--->


<!--- Check to see if the name is supplied. --->
<cfif !structKeyExists( url, "name" )>

	<!--- Stop any further processing of this resource. --->
	<cfthrow
		type="BadRequest"
		message="The Name attribute is missing from the request."
		errorcode="11011"
		/>

</cfif>

<!--- Validate name value. --->
<cfif (
	!len( url.name ) ||
	(len( url.name ) gt 40) ||
	reFindNoCase( "[^a-z\s'-]", url.name )
	)>

	<!--- Stop any further processing of this resource. --->
	<cfthrow
		type="BadRequest"
		message="The Name attribute must be between 1 and 40 characters and may only contain letters, spaces, dashes, and apostrophes."
		errorcode="11012"
		/>

</cfif>

<!--- Check to see if age is supplied. --->
<cfif !structKeyExists( url, "age" )>

	<!--- Stop any further processing of this resource. --->
	<cfthrow
		type="BadRequest"
		message="The Age attribute is missing from the request."
		errorcode="11021"
		/>

</cfif>

<!--- Validate age value. --->
<cfif (
	!isNumeric( url.age ) ||
	(url.age lt 0) ||
	(url.age gt 99)
	)>

	<!--- Stop any further processing of this resource. --->
	<cfthrow
		type="BadRequest"
		message="The Age attribute must be a number between 0 and 99 (inclusive)."
		errorcode="11022"
		/>

</cfif>


<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->


<!---
	If we made it this far, the supplied resource attributes are
	valid. Now, let's create a fake resource for the demo.
--->
<cfset request.response = {} />
<cfset request.response[ "id" ] = randRange( 1000, 9999 ) />
<cfset request.response[ "name" ] = url.name />
<cfset request.response[ "age" ] = url.age />