This document discusses building REST APIs with ColdBox by transforming a ColdBox application into an API that is accessed through a RESTful interface. It covers the basic steps of starting with a headless API module, building URI routes with resources and actions, handling requests in controllers, and returning data. It also discusses additional topics like status codes, caching, security, restricting HTTP verbs, and error handling to build APIs beyond the basic level.

1. REST APIs
REpresentational State Transfer of an
Application Programming Interface

2. Who Am I?
@Francainath

3. This is what I do:
(+ )
(REST)

4. In the Beginning...

5. Changing landscape

6. Where we are today:

7. PROBLEM:
How can we make our app work on all
these devices?

8. solution #1: RESPONSIVE DESIGN

9. solution #2: CUSTOM APPS
Unique app for each environment

10. Are we gonna write a new app for
EVERY DEVICE?

11. 0:01

13. ColdBox REST

14. REST APIs
REpresentational StateTransfer of an
Application Programming Interface
We are going to transform our
ColdBox program into an API and
access it through a RESTful interface

15. STEP #1: API
Start w/a app

16. STEP #1: API
Make it headless & start api module

17. STEP #2: REST
URI routes are built up w/a combo of
resources and actions
Resources = objects
made/managed thru the model
represented by nouns
Actions = functions
built in the handlers
represented by verbs

18. Basic Handler

19. Routes
Routes = "how we reach our handlers"
built in the ModuleConfig.cfc
Build them up with:
resource (nouns)
action (verbs)

20. basic ModuleConfig.cfc

21. Example routes
List players?
(baseURL)/api/player/list
Get a player? (http verb GET)
(baseURL)/api/player/:playerID
Make a player? (http verb POST)
(baseURL)/api/player/:playerID

22. -­ docs
Returning data
"The most common way to return data
from your handler's action is to use
the even object's renderData()
method. It takes complex data and
turns it into a string representation"

23. Return data formats
XML
JSON
TEXT
WDDX
PDF
HTML

24. Setting up a return

25. Well, that was
Wasn't it?

26. Well, it was...
Bare Bones!

27. 0:03

28. Beyond "bare bones"
Status Codes
Caching
Security
Restricting HTTP Verbs
Error Handling
Relax

29. Status Codes
200 "OK"
202 "Created"
400 "Bad Request"
401 "Unauthorized"
404 "Not Found"
500 "Server Error"

30. Using Status Codes
1. event.renderData() (shortcut)
statusCode & statusMessage attr
2. event.setHTTPHeader() (manual)
statusCode & statusText attr

31. Restricting HTTP verbs
in our routes, we mapped HTTP verbs
to handler actions, but how can we
prevent users from hitting resources
w/the wrong verbs? (aka a GET to a
delete function)

32. this.allowedMethods
allowedMethods property in handler
can restrict those connections for us

33. RELAX!!!
and now...

34. Resources
Coldbox REST docs
http://wiki.coldbox.org/wiki/Building_Rest_APIs.cfm
Coldbox REST Refcard (PDF)
https://github.com/ColdBox/cbox-­
refcards/raw/master/ColdBox%20REST%20APIs/Cold
REST-­APIs-­Refcard.pdf
Coldbox Relax docs
http://wiki.coldbox.org/wiki/Projects:Relax.cfm