6.x
For Newbies
Getting Started
HMVC
Digging Deeper
Architecture Concepts
External links
RESTFul Data
Out of the box, ColdBox gives you all the RESTFul capabilities you will need to create robust and scalable RESTFul services. Let's add some RESTFul capabilities to our contact listing we created in the previous section.
Producing JSON
If you know beforehand what type of format you will be responding with, you can leverage ColdBox auto-marshalling in your handlers. By default, ColdBox detects any return value from handlers and if they are complex it will convert them to JSON automatically for you:
contacts.cfc
1
any function index( event, rc, prc ){
2
return contactService.getAll();
3
}
Copied!
ColdBox detects the array and automatically serializes it to JSON. Easy Peasy!
renderData()
The request context object has a special function called
renderData() that can take any type of data and marshall (convert) it for you to other formats like xml, json, wddx, pdf, text, html or your own type.Tip: You can find more information at the API Docs for
renderData() here http://apidocs.ortussolutions.com/coldbox/current/index.html?coldbox/system/web/context/RequestContext.html#renderData()So let's open the
handlers/contacts.cfc and add to our current code:contacts.cfc
1
any function index( event, rc, prc ){
2
prc.aContacts = contactService.getAll();
3
event.renderData( data=prc.aContacts, formats="xml,json,pdf,html" );
4
}
Copied!
We have added the following line:
1
event.renderData( data=prc.aContacts, formats="xml,json,pdf,html" );
Copied!
This tells ColdBox to render the contacts data in 4 formats: xml, json, pdf and html. WOW! So how would you trigger each format? Via the URL of course.
Format Detection
ColdBox has the ability to detect formats via URL extensions or an incoming
Accepts header. If no extension is sent, then ColdBox attempts to determine the format by inspecting the Accepts header. If we still can't figure out what format to choose, the default of html is selected for you.1
# Default: The view is presented using no extension or html,cfm
2
http://localhost:{port}/contacts/index
3
http://localhost:{port}/contacts/index.html
4
http://localhost:{port}/contacts/index.cfm
5
6
# JSON output
7
http://localhost:{port}/contacts/index.json
8
# OR Accepts: application/json
9
10
# XML output
11
http://localhost:{port}/contacts/index.xml
12
# OR Accepts: application/xml
13
14
# PDF output
15
http://localhost:{port}/contacts/index.pdf
16
# OR Accepts: application/pdf
Copied!
Tip: You can also avoid the extension and pass a URL argument called
format with the correct format type: ?format=json.Routing
Let's add a new route to our system that is more RESTFul than
/contacts/index.json. You will do so by leveraging the application's router found at config/Router.cfc. Find the configure() method and let's add a new route:1
2
// Restuful Route
3
route(
4
pattern="/api/contacts",
5
target="contacts.index",
6
name="api.contacts"
7
);
8
9
// Default Route
10
route( ":handler/:action?" ).end();
Copied!
The
route() method allows you to register new URL patterns in your application and immediately route them to a target event. You can even give it a human readable name that can be later referenced in the buildLink() method.Make sure you add routes above the default ColdBox route. If not, your route will never fire.
We have now created a new URL route called
/api/contacts that if detected will execute the contacts.index event. Now reinit the application, why, well we changed the application router and we need the changes to take effect.Tip: Every time you add new routes make sure you reinit the application:
http://localhost:{port}/?fwreinit.You can now visit the new URL pattern and you have successfully built a RESTFul API for your contacts.
1
http://localhost:{port}/api/contacts.json
Copied!
Last modified 1d ago
Copy link
Edit on GitHub