This post is a continuation from a previous post detailing all available templates provided by the Ortus Team for new ColdBox projects. Check it out first before continuing!
Before you get started with an API template you should know that both options implement:
This is a CFC that provides a consistent approach to working with an API. Please read up on the docs page before using these templates.
Its purpose is to add some much needed features missing in a standard handler response. Such as setting status codes, content-type, and formatting return data. As well as automatic trapping of the following exceptions:
InvalidCredentials, ValidationException, EntityNotFound, RecordNotFound. Logging, time tracking, and some development level headers for current route information.
ColdBox Security (cbSecurity) is a security plugin that provides a layer of security for your app by providing authentication via JWT Tokens for APIs. Additionally, it provides a very simple way to limit access to your api through annotations and route level security levels. This is its main purpose, however this is a very high level description of the module, it does a lot more and if your interested check out the docs!
On to the templates!
The REST Template
This template takes the simplest approach for building an api which is using the coldbox router to direct you to a handler. This way you can use the router to do any custom routing (e.g.
handlers/users.cfc). The router also allows you to define which METHODS are allowed
The REST HMVC Template
This template uses nested modules to organize the API. This takes advantage of ColdBox conventions which will use nested module names to automatically create routes. In the root of the project there should be a
modules_app folder. This is for modules you create.
This template comes with a module named
api and inside of it is a
modules_app folder that contains a module named
v1. This will automatically generates a url accessible path to
/api/v1 from your project. Then within the
v1 folder any handlers created will be accessible via their configured routes located in
This approach provides an easy way to organize future versions such as
v2,v3,v4,... with little to no changes, just copy the folder, rename it and start working on the new features.
A great example of this is Gavin Pikin's webinar on Building Quick APIs, he creates over 30 versions of an API to show progressive enhancement of his soapbox API and does it with no major routing changes.
This also shows off some really cool ColdBox modules available on https://forgebox.io for security, and using an developing with an ORM, be sure to check it out, its free!