Skip to content

coldbox-templates/rest

Repository files navigation


ColdBox Snapshots Total Downloads Latest Stable Version Apache2 License

Copyright Since 2005 ColdBox Platform by Luis Majano and Ortus Solutions, Corp
www.coldbox.org | www.ortussolutions.com


REST API Application Template

This template gives you the base for building RESTFul web services with ColdBox and securing them with CBSecurity. It is fully documented with swagger/open API specs and you can find them in the resources folder or by running the cbswagger module directly: http://localhost:{port}/cbswagger.

The handlers all leverage the ColdBox REST Handler: https://coldbox.ortusbooks.com/digging-deeper/rest-handler

Implicit Methods

The base handler implements an around handler approach to provide consistency and the following actions:

  • onError - Fires whenever there is a runtime exception in any action
  • onInvalidHTTPMethod - Fires on invalid HTTP method access
  • onMissingAction - Fires on invalid missing actions on handlers

Utility Functions

We also give you some utility functions for RESTFul building:

  • onInvalidRoute - Can be used to fire of route not founds via 404
  • onExpectationFailed - Can be called when an expectation of a request fails, like invalid parameters/headers etc.
  • onAuthorizationFailure - Can be called to send a NOT Authorized status code and message.

HTTP Security

By default the base handlers leverages ColdBox method security via the this.allowedMethods structure:

this.allowedMethods = {
    "index"     : METHODS.GET,
    "get"       : METHODS.GET,
    "list"      : METHODS.GET,
    "update"    : METHODS.PUT & "," & METHODS.PATCH,
    "delete"    : METHODS.DELETE
};

HTTP Methods

The base handler contains a static construct called METHODS that implements basic HTTP Methods that you can use for messages and allowed methods.

METHODS = {
    "HEAD"      : "HEAD",
    "GET"       : "GET",
    "POST"      : "POST",
    "PATCH"     : "PATCH",
    "PUT"       : "PUT",
    "DELETE"    : "DELETE"
};

Status Codes

The base handler contains a static construct called STATUS that implements basic HTTP status codes you can use:

STATUS = {
    "CREATED"               : 201,
    "ACCEPTED"              : 202,
    "SUCCESS"               : 200,
    "NO_CONTENT"            : 204,
    "RESET"                 : 205,
    "PARTIAL_CONTENT"       : 206,
    "BAD_REQUEST"           : 400,
    "NOT_AUTHORIZED"        : 401,
    "NOT_FOUND"             : 404,
    "NOT_ALLOWED"           : 405,
    "NOT_ACCEPTABLE"        : 406,
    "TOO_MANY_REQUESTS"     : 429,
    "EXPECTATION_FAILED"    : 417,
    "INTERNAL_ERROR"        : 500,
    "NOT_IMPLEMENTED"       : 501
};

Quick Installation

Install the template dependencies by running the install command:

box install

This will setup all the needed dependencies for each application template. You can then start the embedded server:

box server start

Code to your liking and enjoy!

Dockerfile

We have included a build/Dockerfile so you can build docker containers from your source code. We have also added two scripts in your box.json so you can build the docker image and run the docker image using our CommandBox Docker containers.

# Build a docker **container**
run-script docker:build
# Run the container
run-script docker:run
# Go into the container's bash prompt
run-script docker:bash

Docker Compose Stack

We have included a build/docker-compose.yaml stack that can be used to run the application in a container alongside a database. We have included support for MySQL, PostgreSQL and MSSQL. We have also included the run-script docker:stack command you so you compose the stack up or down.

run-script docker:stack up
run-script docker:stack down

VSCode Helpers

We have included two vscode helpers for you:

  • .vscode/settings.json - Includes introspection helpers for ColdBox and TestBox
  • .vscode/tasks.json - Tasks to assist in running a Test Bundle and a CommandBox Task

We have included two custom tasks:

  • Run CommandBox Task - Open a CommandBox task and run it
  • Run TestBox Bundle - Open the bundle you want to test and then run it

To run the custom tasks open the command palette and choose Tasks: Run Build Task or the shortcut ⇧⌘B

Welcome to ColdBox

ColdBox Hierarchical MVC is the de-facto enterprise-level HMVC framework for ColdFusion (CFML) developers. It's professionally backed, conventions-based, modular, highly extensible, and productive. Getting started with ColdBox is quick and painless. ColdBox takes the pain out of development by giving you a standardized methodology for modern ColdFusion (CFML) development with features such as:

Learning ColdBox

ColdBox is the defacto standard for building modern ColdFusion (CFML) applications. It has the most extensive documentation of all modern web application frameworks.

If you don't like reading so much, then you can try our video learning platform: CFCasts (www.cfcasts.com)

ColdBox Sponsors

ColdBox is a professional open-source project and it is completely funded by the community and Ortus Solutions, Corp. Ortus Patreons get many benefits like a cfcasts account, a FORGEBOX Pro account and so much more. If you are interested in becoming a sponsor, please visit our patronage page: https://patreon.com/ortussolutions

THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12