Resourceful Routes

Resourceful routes are convention based to help you create routing with less boilerplate.

In ColdBox, you can register resourceful routes (resources()) to provide automatic mappings between HTTP verbs and URLs to event handlers and actions by convention. By convention, all resources map to a handler with the same name or they can be customized if needed. This allows for a standardized convention when building routed applications and less typing 😉

// Creates all resources that point to a photos event handler by convention
resources( "photos" );

// Register multiple fluently
resources( "photos" )
    .resources( "users" )
    .resources( "contacts" );

// Creates all resources to the event handler of choice instead of convention
resources( resource="photos", handler="MyPhotoHandler" );

// All resources in a module
resources( resource="photos", handler="photos", module="api" );

// Resources in a ModuleConfig.cfc
router.resources( "photos" )
  .resources( resource="users", handler="user" )

This single resource declaration will create all the necessary variations of URL patterns and HTTP Verbs to actions to handle the resource. Please see the table below with all the permutations it will create for you.

VerbRouteEventPurpose

GET

/photos

photos.index

Get all photos

GET

/photos/new

photos.new

Return the HTML form for creating a photo

POST

/photos

photos.create

Create a photo

GET

/photos/:id

photos.show

Show a photo by id

GET

/photos/:id/edit

photos.edit

Return the HTML form for editing the photo

PUT/PATCH

/photos/:id

photos.update

Update a photo by id

DELETE

/photos/:id

photos.delete

Delete a photo by id

For in-depth usage of the resources() method, let's investigate the API Signature:

/**
 * Create all RESTful routes for a resource. It will provide automagic mappings between HTTP verbs and URLs to event handlers and actions.
 *
 * By convention the following rules apply
 * - The name of the resource maps to the name of the event handler
 * - The default paremeter name is called `:id`
 * - The available actions are: index, new, create, show, edit, update, delete
 *
 * Example: `resource = photos` Then we will create the following routes:
 * - `/photos` : `GET` -> `photos.index` Display a list of photos
 * - `/photos/new` : `GET` -> `photos.new` Returns an HTML form for creating a new photo
 * - `/photos` : `POST` -> `photos.create` Create a new photo
 * - `/photos/:id` : `GET` -> `photos.show` Display a specific photo
 * - `/photos/:id/edit` : `GET` -> `photos.edit` Return an HTML form for editing a photo
 * - `/photos/:id` : `PUT/PATCH` -> `photos.update` Update a specific photo
 * - `/photos/:id` : `DELETE` -> `photos.delete` Delete a specific photo
 *
 * @resource      The name of a single resource to map
 * @handler       The handler for the route. Defaults to the resource name.
 * @parameterName The name of the id/parameter for the resource. Defaults to `id`.
 * @only          Limit routes created with only this list or array of actions, e.g. "index,show"
 * @except        Exclude routes with an except list or array of actions, e.g. "show"
 * @module        If passed, the module these resources will be attached to.
 * @namespace     If passed, the namespace these resources will be attached to.
 * @pattern       If passed, the actual URL pattern to use, else it defaults to `/#arguments.resource#` the name of the resource.
 * @meta          A struct of metadata to store with ALL the routes created from this resource
 */
function resources(
	required resource,
	handler,
	parameterName    = "id",
	only             = [],
	except           = [],
	string module    = "",
	string namespace = "",
	string pattern   = "",
	struct meta      = {}
){

Scaffolding Resources

We have created a scaffolding command in CommandBox to help you register and generate resourceful routes. Just run the following command in CommandBox to get all the help you will need in generating resources:

coldbox create resource help

API Resourceful Routes

If you are building mostly API routes and not full HTML app routes, you can use the shortcut method apiResources() method instead. This method will work the same as above BUT it will exclude the new and edit actions for you since we are in API Land.

apiResources( "users" );
apiResources( "photos" );
VerbRouteEventPurpose

GET

/photos

photos.index

Get all photos

POST

/photos

photos.create

Create a photo

GET

/photos/:id

photos.show

Show a photo by id

PUT/PATCH

/photos/:id

photos.update

Update a photo by id

DELETE

/photos/:id

photos.delete

Delete a photo by id

Here is the full method signature:

/**
 * Create all API RESTful routes for a resource. It will provide automagic mappings between HTTP verbs and URLs to event handlers and actions.
 *
 * By convention the following rules apply
 * - The name of the resource maps to the name of the event handler
 * - The default paremeter name is called `:id`
 * - The available actions are: index, create, show, update, delete
 *
 * Example: `resource = photos` Then we will create the following routes:
 * - `/photos` : `GET` -> `photos.index` Get a list of photos from the API
 * - `/photos` : `POST` -> `photos.create` Create a new photo
 * - `/photos/:id` : `GET` -> `photos.show` Get a specific photo from the API
 * - `/photos/:id` : `PUT/PATCH` -> `photos.update` Update a specific photo
 * - `/photos/:id` : `DELETE` -> `photos.delete` Delete a specific photo
 *
 * @resource      The name of a single resource to map
 * @handler       The handler for the route. Defaults to the resource name.
 * @parameterName The name of the id/parameter for the resource. Defaults to `id`.
 * @only          Limit routes created with only this list or array of actions, e.g. "index,show"
 * @except        Exclude routes with an except list or array of actions, e.g. "show"
 * @module        If passed, the module these resources will be attached to.
 * @namespace     If passed, the namespace these resources will be attached to.
 * @pattern       If passed, the actual URL pattern to use, else it defaults to `/#arguments.resource#` the name of the resource.
 * @meta          A struct of metadata to store with ALL the routes created from this resource
 */
function apiResources(
	required resource,
	handler,
	parameterName    = "id",
	only             = [],
	except           = [ "new", "edit" ],
	string module    = "",
	string namespace = "",
	string pattern   = "",
	struct meta      = {}
){

Last updated