Skip to content

Mach II 1.9 Endpoints

Jump to bottom Edit New page
thofrey edited this page Apr 1, 2014 · 5 revisions

By Peter J. Farrell and Kurt Wiersma

Table of Contents

  1. Introduction
  2. Endpoints in Detail
  3. Implementation Specifications and How Mach-II Routes Endpoints
  4. Bundled Endpoints
  5. Other Mach-II Packages That Could Leverage Endpoints
  6. Dashboard

Introduction

The age-old question when developing Mach-II applications is how other technologies like AJAX, REST, web services and serving content like images / documents fit into a Mach-II application. Most of the time these type of services need to connect to backend services but the result of the request is meant to be used by a computer (non-UI). The result could be a document or image, JSON, XML or other computer readable format. Mach-II endpoints aim to solve the problem of how these technologies work within a Mach-II application by providing a developer extensible hook (endpoint) into your application where requests are processed and results furnished to the requestor.

Endpoints in Detail

In all simplicity, endpoints are simple and lightweight "servlet" like handlers that accept requests and respond to them as required. Most endpoints will be used for non-human interactions, they are purposedly designed to be lightweight, and singular in purpose by performing without the need of plugins, filters, subroutines or other Mach-II constructs that the full Mach-II request lifecycle provides.

An endpoint should respond in a manner that is valid for the type of endpoint it is. For example, you might be using the file endpoint which can validate that the user requesting the document has the permissions to do so and then use cfcontent or Apache mod-sendfile to serve the protected document. Another example would be a RESTfule endpoint that would return JSON/XML/HTML back to the requestor.

Endpoints offer a lot of syntactical sugar which provides ease of use for the developer. For example, RESTFul services are easy to develop and allows you to interact with your pre-existing service layer. REST endpoints offers greater flexibility and robustness than for Team Mach-II to "bolt-on" some sort of REST like functionality on top of event-handlers directly.

Since endpoints are registered with the framework itself, the deployment of Mach-II applications that leverage other technologies would be simplified. Other projects like the Mach-II Dashboard already leverage a file endpoint to server Dashboard assets like JS/CS/images. This allow you to use the Dashboard without having to drag and drop asset files into web browser accessible location.

Implementation Specifications and How Mach-II Routes Endpoints

Defining Endpoints

Endpoints are defined in the <endpoints> XML in your mach-ii.xml configuration or via the API by other components that need to register an endpoint. An endpoint can be configured by providing <parameter>s in the XML while other endpoints are designed to be extended where custom logic is implemented in your code. All registered endpoints are global in nature and would transverse any modules (similar to how loggers are).

Routing Endpoints

We allow endpoints to be routed in two ways:

  • The simplest way endpoints would be routed is through the index.cfm?endpoint=x file like your regular Mach-II events. The desired endpoint is indicated in URL parameters.
  • Custom endpoint paths can be configured (/rest/index.cfm -> /rest/?param1=abc) in which the endpoint name is not required in the URL itself. A blank file just needs to exists in the directory. The Mach-II bootstrapper takes care of figuring out the endpoint name and routing parameters.

Endpoint Request Lifecycle

All endpoints would extend MachII.framework.endpoints.AbstractEndpoint which offers several methods that can be implemented:

  • configure() - like any other Mach-II extended component
  • deconfigure() - like any other Mach-II extended component
  • preProcess() - runs at the beginning of an endpoint request (if implemented) and is similar to the preProcess plugin point
  • handleRequest() - processes the endpoint and performing things API interactions
  • postProcess() - runs at the end of an endpoint request (if implemented) and is similar to the postProcess plugin point
  • onAuthenticate() - a special point that is kicked between the preProcess and handleRequest endpoint request lifecycle. This method can be pragmatically run if isAuthenticationRequired() method is implemented and returns true
  • onException() - a special point that is called when an exception occurs during the execution of the endpoint request

All endpoints request lifecycle methods get passed a Mach-II Event object for the preProcess(), onAuthenticate(), handleRequest(), postProcess() and onException()\ methods.

The endpoint request lifecycle is (after the endpoint is loaded):

  1. preProcess() - if implemented
  2. onAuthenticate() - if implemented or if isAuthenticationRequired() is implemented and returns true for the request
  3. handleRequest() - required
  4. postProcess() - if implemented
  5. *onException() is called pragmatically if an un-handled exception occurs during the endpoint request lifecycle

Additional Endpoint Features / Implementation Details

  • Any DI engine (such as ColdSpring) provides autowire endpoint CFCs files via the "depends" attribute
  • All endpoints have access to the Mach-II properties and Mach-II environments settings
  • All endpoints are stateless (similar to Mach-II filters, listeners, etc.) and a singleton therefore they need to be thread safe.

Bundled Endpoints

File Serving (1.9+)

Main article: Introduction to File Endpoints

Serves protected files via cfcontent or using Apache mod-x-sendfile. Developers can either set configuration and use the base endpoint or extend the base endpoint in order to build custom logic on the base. This endpoint supports 304 Not Modified responses, file timestamps appended on file paths for easy browser caching via unique URIs and serving of the result of .cfm file with MIME-type piping (which allows you to build a .css file in a .cfm and pipe it to the CSS MIME-type).

Extend: MachII.endpoints.file.BaseEndpoint

Scheduled Tasks (1.9+)

Main article: Introduction to Scheduled Task Endpoints

Registers/unregisters scheduled tasks with an authenticate and secure endpoint URLS for cfschedule to target. This endpoint simplifies deployment headache since any task methods are automatically registered as a scheduled task in your CFML engine. This endpoint is automatically secured with basic HTTP authentication and is configured by extending the base endpoint and writing functions/methods with annotations.

Extend: MachII.endpoints.task.BaseEndpoint

REST (1.9+)

Main article: Introduction to REST Endpoints

This endpoint takes care of handling of the HTTP verbs and URI routing which simplifies the all the grunt work required to route REST based URIs. Best of all, developers build REST APIs by extending our base endpoint CFC and use annotations in the function/ method signatures to provide configuration data. No messy XML syntax required.

The REST endpoint is easily secured via the onAuthenticate() method either with a custom built authentication schema or using the basic HTTP access authorization module that is bundled with Mach-II. We also support sending the HTTP verb via an custom HTTP header (x-http-method-override) or via a custom URL string parameter (_method) which allows you to make REST calls with PUT and DELETE via HTML forms.

Example:

    <cffunction name="getUser"
        rest:uri="/user/{userId}"
        rest:accept="GET"
        rest:format="json,html">
        <cfargument name="userId" required="true" type="String" />
        ...
    </cffunction>

Extend: MachII.endpoints.rest.BaseEndpoint

Additional Planned Functionality - Mach-II 2.0

  • Respond to requested response format provided in request header (Accepts: application/json)
  • Provide a standard collection of response codes and a pattern for returning them - ticket (trac-wiki) #717 "task: Research common return headers for REST endpoints and implement helper ... (closed: wontfix)")
  • Caching with possible ETag support

Custom Endpoints

Have an ideas for an endpoint? No problem. Create your custom endpoint by extending MachII.endpoints.AbstractEndpoint and implement the features you need.

Other Mach-II Packages That Could Leverage Endpoints

  • The HtmlHelperProperty could implement an endpoint that serves on-the-fly Javascript file compression and concatenation.

Dashboard

We're building a REST endpoint into the Mach-II Dashboard which will provide hooks for ANT scripts. We will also use this functionality to build cluster capabilities into the Dashboard which will allow The Mach-II Dashboard could implement an endpoint that offers REST like hooks for ANT scripts. This could also be used to build cluster capabilities into the Dashboard. This would allow one Dashboard to communicate to other Dashboards running the same application in a clustered environment.

Add a custom footer
Add a custom sidebar
Clone this wiki locally