In this session we will review all of the RESTful capabilities of ColdBox. We will then go into modeling mode and model a RESTful service using the ColdBox Relax Module and finally implement the running service. But there's more, we will then document the entire service for you.

1. www.intothebox.org

2. 4.0 rebuilt from the ground-up to make building
RESTful services a breeze

3. RESTful-ly Goodness
Simplify common API Tasks
• Coldbox Routing
• Request Context:
renderData();
getHTTPHeader();
getHTTPMethod();
• Coldbox Proxy
• Modularity
• Interceptors

4. Powerful Routing Configuration
// API Routing
var defaultAPIActions = {
"GET":"index",
"POST":"add",
"PUT":"onInvalidHTTPMethod",
"PATCH":"onInvalidHTTPMethod",
"DELETE":"onInvalidHTTPMethod"
};
var defaultEntityActions = {
"GET":"get",
"PUT":"update",
"PATCH":"update",
"DELETE":"delete"
};
//Users API Routes
addRoute(
pattern='/api/v1/users/:id',
handler='api.v1.Users',
action=defaultEntityActions
);
addRoute(
pattern='/api/v1/users',
handler='api.v1.Users',
action=defaultAPIActions
);

5. Built-In Methods to Minimize Duplication of Effort
function preHandler(event,action,eventArguments,rc,prc){
rc.format="JSON";
//404 default
rc.statusCode=STATUS.NOT_FOUND;
rc.data = {};
event.noLayout();
//handle any content payloads
if(
len(getHttpRequestData().content)
and
isJson(getHttpRequestData().content)
) structAppend(rc, deserializeJson(getHttpRequestData().content),true);
//set our access control allow origin header for cross-domain requests
header name="Access-Control-Allow-Origin" value="*";
//process our login tokens
processAuthenticationTokens(argumentCollection=arguments);
prc.currentUser = SessionService.getCurrentUser();
}
preHandler()

6. Built-In Methods to Minimize Duplication of Effort
function postHandler(event,action,eventArguments,rc,prc){
event.renderData(
type=rc.format,
data=rc.data,
statusCode=rc.statusCode,
statusMessage=event.getValue(“statusMessage”, “Success”)
);
}
postHandler()

7. Pre-configured REST App Template
mkdir myapi --cd
coldbox create app skeleton=rest name=MyService --installColdBox
server start --rewritesEnable

8. A powerful, R.A.D. framework
for building REST APIs

10. API Documentation
• Helps to define coding conventions
• Allows API evolution to maintain consistency and
standards
• Decreases onboarding time and increases
adoption for API consumers
• Provides flexibility in development sprint planning
by allowing members, owners, and stakeholders
to visualize the product and ensure needs are met
RELAX
A business case for developers:

11. Next Generation
RELAX
• Open and transferrable documentation using OpenAPI
(fka Swagger)
• Maintain backward compatibility for RelaxDSL (for a
time)
• Minimize the need for duplication of effort
• Streamline the drill-down process to the response level
• Make documentation authoring and revisions pain-free

12. Next Generation
RELAX
Integrated
Responsive
Descriptive
Exportable
Extendable
Navigable

13. Next Generation
RELAX
Drill down quickly
to paths, methods,
schemas and
samples
References and
internal document
links
Extend OpenAPI
schema to
(near)infinite

14. Next Generation
RELAX
Fully recursive to
allow for automation
and uniform
consumption of
documentation
resources

15. Long-term…
RELAX
Evaluate and evolve
through innovation
and by incorporating
the best features of
API Tools, integrating
them into a single
workflow

16. A Tour
RELAX

17. API Development
Lessons Learned:
• Maintain consistency in responses to minimize conditionals
in consumption
• Implement your paging and throttling strategies *NOW*!
• Standardize error handling
• Less is *more* (Massive data dumps kill your API)
• Marshall deeply nested arrays into hashmap representations,
whenever possible. Recursion kills.

18. API Development
Lessons Learned:
GET
POST
PUT
PATCH
DELETE
HEAD
OPTIONS
http://www.restapitutorial.com/lessons/httpmethods.html

19. API Development
Lessons Learned:
http://www.restapitutorial.com/httpstatuscodes.html

20. API Development
Lessons Learned:
200 - “You wanted it... Here you go, buddy:”
201 - “I've created something new for you!”
202 - “Your request is accepted, heres a URL so you
can check the status:”
203 - “Here's a record, but we haven't confirmed
persistence”
204 - “I deleted what you told me. Now it's nothing,
so... Here's nothing!:”
205 - “A record has been updated while you were
slacking off. Re-request the data and refresh your
view.”
206 - “There are, like, a gazillion rows, man. Here's 25
of them so I don't break

21. Q&A
RELAX
REST
&

22. Next Session Begins @ 11:15AM