CF Objective Notes - Creating Services for Modern Web Applications

May 16, 2014

Creating Services for Modern Web Applications
Mike Nimer

in a simpler time, server side rendering
request / response model
server side rendering is dead (unless you need a static site for search engine spiders)

modern web apps
single pages apps
data loading via ajax
client side logic
client side routing

but can't move EVERYTHING to the client
still need server for data storage, email, encryption, etc
in the world of CF, need to think of our apps as CFCs

connect these via REST or Web Sockets
REST – Representational State Transfer
Roy Thomas Fielding wrote a dissertation on this (he's an architect at Adobe now)

REST Constraints

Uniform interface
the url means something. It points to an item
client server
servers are not concerted with the ui OR the USER STATE
servers and clients may also be replaced and developed independently

if you have an AGREED UPON interface between client and server code, you can link them up pretty seamlessly with minimal time needed to test between the 2

Stateless
each request from any client contains ALL the info necessary to serve the request
might still put in caching/optimization, but the app still basically gets back all the data it needs

Cacheable
have to assume that the browser is going to cache a lot
if you don't want it to, you have to explicitly tell it not to

Layered System
client shouldn't KNOW it's not hitting the database directly, that there are 5 layers in between, etc

Code on Demand (optional in REST)
the ability to return "executable code" via REST

Evolution of REST
Martin Fowler "The Richardson Maturity Model"
Level 0 – the swamp of POX
call a URL, get back XML
url is just an end point
access="remote" in CF

level 1
Unique URL for each resource
but only use "get" or "post"
cfcomponent rest ="true" in CF
UPDATE and DELETE – those verbs are still in the URL. That's what we want to get past

Level 2
this is where people say "i'm using a proper REST service"
correct usage of verbs
get
post
put
patch
delete

and hopefully they're using correct status codes
this is "machine to machine"
need to give as much correct info as possible

REST URL design
keep in mind "verbs are bad"
nouns are good
okay: /jobhistory
not okay: /getupdatehistory

URLS have implicit hierarchy
/order/123/products/123125
URLS represent a resource
Use HTTP method to figure out what to do with it (update, delete, etc)

Twitter
uses POST
post friendship/users/
etc

Delicious
uses end points
level 0

REST good URLS
GET: /user/{id}
POST: /user/{id}
PUT
DELETE
...all use SAME url

non resources

GET /search?q=
GET /translate?from={...}&to={..}

CF Admin REST settings
create a path to where the CFCs are
it will parse all the CFCs, parse them into Java Rest Services
(if you change something you have to redo this step, it doesn't automatically happen. Have to recompile.)

REST Status Codes
important b/c this is "machine to machine"
http://infoq.com/articles/webber-rest-workflow
200 = OK
201 = created, don't need to return the whole object if I just need to know it's done, can just return 201 code
202 – accepted "i got it, I'm working on it. Don't freak out, you can show the progress bar now"
303- you need to go somewhere else. Everything is ok but you're in the wrong place
400 – you put something badly formatted in the url
405 – you used "get" and should have used "delete", etc (there's another verb to "ask what's available")
406 – you requested json and all I can return is XML, etc
409 – conflict. Someone saved this record before you did. Client should then show some sort of UI update so the user knows what to do.
412 – precondition failed
415 – unsupported media time. You posted an MPEG and I don't know what to do with it
500 – the ultimate lazy response. Server: "i don't know what to tell you about what went wrong" Cross your fingers and hope you can debug it.

Level 3 – Hypermedia
the one nobody understands
"self documenting service"
services return info about what else can be done
"get me this user" also returns "how to update the user, how to promote him, how to fire him" etc
client looks for these extra links to find 'what else can I do?'
machine to machine – so on-line user docs don't count for this
have to document how you're returning things in your api

etc

if clients are driven this way, you can add/remove stuff from your API and none of the clients will break.

Twitter search API does this
you get a "next_results" back so yo don't have to do any work to figure out the query string for "page 2" in the search results
if you don't have a "previous" in the response, you're on page 1