rest
template is a basic REST template that does not rely on modules or versioning. If you would like to add versioning and HMVC modularity use the rest-hmvc
template. You can also find a full demo here: https://github.com/lmajano/hmvc-presso-demo​CFHTTP
tag) can send requests to a URI to interact with it. The HTTP verb (GET, POST, etc) sent in the header of the request tells the server how the client wants to interact with that resource.https://api.example.com
), or after a static placeholder that differentiates it from the rest of the app (https://www.example.com/api/
). We'll use the latter for these examples.user
. Resources should usually be nouns. If you have a verb in your URL, you're probably doing it wrong.GET /api/user
will return a representation of all the users. It is permissible to use a query string to control pagination or filtering.POST /api/user/
will create a new userGET /api/user/53
will return a representation of user 53PUT /api/user/53
will update user 53DELETE /api/user/53
will delete user 53/api/user
resource is to create a handler called user.cfc
in the /handlers/api/
directory. In this instance, ColdBox will consider the api
to be a handler package. You can leverage CommandBox for this:user.cfc
handler is /api/user
, but what if we want the resource in the URL to be completely different than the handler name convention? To do this, use the /config/Router.cfc.
file to declare URL routes we want the application to capture and define how to process them. This is your URL Router and it is your best friend!route-visualizer
module to visualize the router graphically. This is a huuuuge help when building APIs or anything with routes.install route-visualizer
struct
can also be provided that maps different verbs to different actions. This gives you exact control over how the requests are routed. We recommend you check out our Routing DSL guide as you can build very expressive and detailed URL patterns.:userID
part of the route pattern is a placeholder. It matches whatever text is in the URL in that position. The value of the text that is matched will be available to you in the request collection as rc.userID
. You can get even more specific about what kind of text you want to match in your route pattern.-numeric
to the end of the placeholder to only match numbers.addRoute( pattern = 'user/:userID-numeric' );
user/123
but not user/bob
.-alpha
to the end of the placeholder to only match upper and lowercase letters.addRoute( pattern = 'page/:slug-alpha' );
page/contactus
but not page/contact-us3
.addRoute( pattern = 'api/:resource-regex(user|person)' );
api/user
and api/person
, but not /api/contact
{}
quantifier to restrict how many digits a placeholder should have or be between:/api/users/contact/address/27
which would refer to the address resource inside the contact belonging to a user.String
=> HTMLComplex
=> JSONrenderData()
method. It takes complex data and turns it into a string representation. Here are some of the most common formats supported by event.renderData()
:Accepts
header to determine the right format to use by default or the URI for an extension.extension
to the end of the URL:format
. What's even better is that renderData()
can find the format variable and automatically render your data in the appropriate way. All you need to do is pass in a list of valid rendering formats and renderData()
will do the rest.200
- OK - Everything is hunky-dory201
- Created - The resource was created successfully202
- Accepted - A 202 response is typically used for actions that take a long while to process. It indicates that the request has been accepted for processing, but the processing has not been completed400
- Bad Request - The server couldn't figure out what the client was sending it401
- Unauthorized - The client isn't authorized to access this resource404
- Not Found - The resource was not found500
- Server Error - Something bad happened on the serverrenderData()
. HTTP status codes and messages are not part of the response body. They live in the HTTP header.event.setHTTPHeader()
method in your handler.FORM
and URL
variables as the cache key. To enable event caching, set the following flag to true in your ColdBox config: Coldbox.cfc
:cache=true
annotation to any action you want to be cached. That's it! You can also get fancy, and specify an optional cacheTimeout
and cacheLastAccesstimeout
(in minutes) to control how long to cache the data.template
cache. You can configure this cache to store its contents anywhere including a Couchbase cluster!coldbox.jsonPayloadToRC = false
withSSL()
and ColdBox will only allow those routes to be accessed securelyAuthorization
that contains a base 64 encoded concatenation of the username and password.event.getHTTPBasicCredentials()
.preHandler()
method which will get automatically run prior to each action in that handler. You can implement a broader solution by tapping into any of the ColdBox interception points such as preProcess
which is announced at the start of every request.eventPattern
annotation to limit what ColdBox events they apply to.event.getHTTPHeader()
to pull specific headers from the HTTP request.ColdBox.cfc
:this.allowedMethods
at the top of your handler. In this handler the list()
method can only be accessed via a GET, and the remove()
method can only be accessed via POST and DELETE.onError()
or the onInvalidHTTPMethod()
convention in your handler or an exception handler which applies to the entire app.onError()
onError()
in a handler, ColdBox will automatically call that method for runtime errors that occur while executing any of the actions in that handler. This allows for localized error handling that is customized to that resource.onInvalidHTTPMethod()
onInvalidHTTPMethod()
in a handler, ColdBox will automatically call that method whenever an action is trying to be executed with an invalid HTTP verb. This allows for localized error handling that is customized to that resource.onError()
convention but covers the entire application. First, configure the event you want called in the ColdBox.cfc
config file. The event must have the handler plus action that you want called.relax
structure to your Coldbox.cfc
file:http://[yourhost]/relax
to view Relax.