Oct 1, 2017

Building a ColdFusion REST Application - TAFFY vs Native ColdFusion tags

I was recently working on converting an existing ColdFusion applications over to a service based architecture (SOA), using REST API on the backend, with a Javascript framework on the front end.  I thought I would share a few points about the process.

The project I was working on chose to go with Taffy but you should consider your all your projects requirements before making a decision.  My intentions with this post is to try and highlight a couple of the differences which might help you make the right decision.

Note: If this topic is all new to you, I would recommend you review a session done back in the CFSummit 2015 called How We Rest.  You can find the slides at the link below and there is a link on the last slide to get code samples as well.

The slides do a great job a drawing out some of the major differences Native ColdFusion, Taffy, FW\1 and ContentBox. It is a few year old presentation, so use it as a good primer on the topic.

If your organization already uses FW\1 or ContentBox, it might be an easier decision.

After using Taffy, I am a big fan of its ease of use and its plug and play nature.  I would use it again in a heartbeat.  

Here are two important areas you might want to consider when picking your solution.

OpenAPI Swagger Support
If you need to support an OpenAPI specification, such as Swagger, you will need to consider how your project or organization need to import or export your APIs.  The need for OpenAPI import and export features will be more important if you are sharing APIs between systems over time.  If you are just using it as part of a migration step, it is not that important as recreating the CFML syntax for the API is not too difficult with most projects.

Coldbox has the ability to export as documented here https://www.forgebox.io/view/cbswagger
FW\1 - I do not see any built in support
Taffy - No direct support.  Although not to hard to put something together if you needed it.

Using the online Swagger editor https://editor.swagger.io/ makes it quite easy to build your  OpenAPI REST specification.  If you look at the top menu bar you have several options with Generating Server or Client shell code along with front end typescript classes as well.

Perhaps one day we will see CFML under Generate Server Code.

If you look at the syntax, you can see a few elements that were added like responseMessages to support the OpenAPI spec.  
<cfcomponent rest="true" restPath="/cookieService" produces="text/plain" >
    <!--- Test with various produces --->
    <cffunction name="sayPlainHelloUser" responseMessages="404:Not Found,200:successful,10:notdefine" access="remote" returnType="String" httpMethod="GET" produces="text/plain">
        <cfargument name="nAme" type="string" restargsource="cOOkie" required="false" default="CF">
        <cfset res="Hello " & name>
        <cfreturn res>

So if need to import \ export OpenAPI specs then you should consider levels of support for each REST solution.  In my recent project it was the front end code generation that was driving the need to OpenAPI.

Overloading Methods
One of the features of the Open API spec is that you can define the GET method several times, using the same REST Path with different arguments and then have the server call the correct method based on incoming arguments.

Since Native ColdFusion supports import and export of OpenAPI you would be correct to assume it is supported within the ColdFusion tags.  The cffunction tag has an attribute called httpmethod which can be GET for many different Functions which are defined with different REST arguments.

Taffy, by design, does not support function overloading.  If you want more then one GET you will need another CFC.  As Taffy uses GET, POST, PUT, Options, Delete as the actual function names, you are blocked from having more than one GET etc.  After talking to Adam Tuttle, the creator or Taffy, he told me Taffy was designed  to remove complexity and to keep the mapping between the REST Path, the CFC and the method as simple as possible.

So this becomes another area to consider if you like having function overloading.

So two important areas to consider.  There are many many more areas to consider but beyond my intentions for this post.  Areas like Token management, Security, Metering, Logging, Analytics etc are all important as well.

I hope this helps you when making the right decision for your ColdFusion REST project.

No comments:

Post a Comment