Experimenting With A JavaScript Gateway To A Remote ColdFusion Persistence API

// Define the Contact Gateway. This module provides access to the
// actual data storage of the contact information. This only knows
// to get access and mutate peristance records - it doesn't know
// anything else about anything.
define(
	[
		"jquery"
	],
	function( $ ){


		// I return an initialize component.
		function ContactGateway( apiUrl ){

			// Store the base API URL. This will be used to help
			// construct all resource URLs.
			this.apiUrl = apiUrl;

			// Store the resource URL for a contact within the API.
			// All access and mutation operations will be performed
			// on this resource.
			this.resourceUrl = (apiUrl + "index.cfm");

			// Return this object reference.
			return( this );

		}


		// Define the class methods.
		ContactGateway.prototype = {


			// I am simply a wrapper around the unerlying jQuery AJAX
			// request that routes and unwrapps the respones payload.
			accessAPI: function( options ){

				// Access the API using the given options.
				var response = $.ajax( options );

				// Decorate the response so that the 200 OK reponses
				// will be properly rejected IF the request is not
				// truly a success.
				response = this.addRoutingPipe( response );

				// Decorate the response so that the data and errors
				// can be extracted as they come throught.
				response = this.addExtractionPipe( response );

				// Return the decorated response promise.
				return( response );

			},


			// I pipe the the response through an unwrapper that
			// extracts the success data or the error message and
			// passes it through to the promise chain.
			addExtractionPipe: function( response ){

				// Unwrap the response payload.
				var unwrappedResponse = response.pipe(
					function( response ){

						// Return the succesful data.
						return( response.data );

					},
					function( response ){

						// Return the rejected error message.
						return( response.code, response.error );

					}
				);

				// Return the piped response.
				return( unwrappedResponse );

			},


			// I pipe the given AJAX request through a switch that
			// checks for a SUCCESS flag. Since all requests come
			// back as 200 OK responses, we need to use the success
			// flag to route the value through the appropriate
			// resolve / reject pipeline.
			addRoutingPipe: function( response ){

				// Pipe the response through our router.
				var routedResponse = response.pipe(
					function( response ){

						// The HTTP response came back; check to see
						// if the API request was a success.
						if (response.success){

							// Simply pass this through to the
							// currently resolved response.
							return( response );

						}

						// The API was a FAILURE. Let's create a new
						// deferred object and reject it.
						return(
							$.Deferred().reject( response )
						);

					},
					function( response ){

						// The API request came back with an unexpected
						// error (ex. HTTP failure, no internet, 500).
						// Return a normalized failed response through
						// to the currently rejected response.
						return({
							success: false,
							data: "",
							code: 500,
							error: ("Unexpected error: " + response.status + " " + response.statusText + ".")
						});

					}
				);

				// Return the routed response.
				return( routedResponse );

			},


			// I delete the contact with the given ID.
			deleteContactById: function( id ){

				// Delete the given contact from the API.
				var response = this.accessAPI({
					type: "post",
					url: (this.resourceUrl + "?action=delete"),
					data: {
						id: id
					},
					dataType: "json"
				});

				// Return the response promise.
				return( response );

			},


			// I get all the contacts.
			getAllContacts: function(){

				// Get all the contacts from the API.
				var response = this.accessAPI({
					type: "get",
					url: (this.resourceUrl + "?action=getAll"),
					data: {},
					dataType: "json"
				});

				// Return the response promise.
				return( response );

			},


			// I get the contact with the given ID.
			getContactById: function( id ){

				// Get the contacts from the API.
				var response = this.accessAPI({
					type: "get",
					url: (this.resourceUrl + "?action=get"),
					data: {
						id: id
					},
					dataType: "json"
				});

				// Return the response promise.
				return( response );

			},


			// I save the given contact information (performing
			// either an insert or an update based on ID).
			saveContact: function( id, name, email ){

				// Insert or Update the given contact on the API.
				var response = this.accessAPI({
					type: "post",
					url: (this.resourceUrl + "?action=save"),
					data: {
						id: (id || 0),
						name: name,
						email: email
					},
					dataType: "json"
				});

				// Return the response promise.
				return( response );

			}


		};


		// -------------------------------------------------- //
		// -------------------------------------------------- //


		// Return the gateway constructor.
		return( ContactGateway );


	}
);