Coldbox API Template Options

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!

What Coldbox template should I use?

How Ghost allows you to turn anonymous readers into an audience of active subscribers, so you know what’s working and what isn’t.

Ares DevelopmentGhost

Before you get started with an API template you should know that both options implement:

REST Handler

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.

REST handler - ColdBox HMVC Documentation

ColdBox HMVC Documentation

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

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!

Module - https://forgebox.io/view/cbsecurity
Docs - https://coldbox-security.ortusbooks.com/getting-started/overview

On to the templates!

The REST Template

GitHub - coldbox-templates/rest: A RESTFul service ColdBox MVC template

A RESTFul service ColdBox MVC template. Contribute to coldbox-templates/rest development by creating an account on GitHub.

GitHubcoldbox-templates

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. /api/users -> handlers/users.cfc). The router also allows you to define which METHODS are allowed GET POST PUT DELETE

The REST HMVC Template

(Hierarchical model–view–controller)

GitHub - coldbox-templates/rest-hmvc: A modular RESTFul API Template

A modular RESTFul API Template. Contribute to coldbox-templates/rest-hmvc development by creating an account on GitHub.

GitHubcoldbox-templates

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.

+ modules_app
  + api
    + models
    + modules_app
      + v1
        + config
          - Router.cfc
        + handlers
          - Auth.cfc
          - Echo.cfc

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 /modules_app/modules_app/v1/config/Router.cfc

/api/v1/auth -> /modules_app/modules_app/v1/handlers/auth.cfc
/api/v1/echo -> /modules_app/modules_app/v1/handlers/Echo.cfc

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.

Gavin Pickin on Building Quick APIs - Extended Version

In this session with Gavin Pickin, we will use ColdBox’s built in REST BaseHandler, and with CBSecurity and Quick ORM we will setup a secure API using fluent query language - and you’ll see how Quick Quick development can be!

CFCastsOrtus Solutions

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!