Upload
elastic-path
View
1.008
Download
3
Embed Size (px)
DESCRIPTION
Featured talk by Senior Product Architect Matt Bishop: HATEOAS Your Cake and Eat It Too: Turning Complex Business Processes into an Easy-To-Use API We set out to build a HATEOAS server that had all the bells and whistles, only to find, well, not many pre-existing bells and whistles. By necessity we had to build our own HATEOAS server and figure out how to turn our complex ecommerce process into an API that required little training to succeed with. This talk will cover that journey and give some insight as to how to do it yourself.
Citation preview
Matt Bishop
Product Architect at Elastic Path
Built an e-commerce HATEOAS API
18-month effort
20-person dev team
Transforming Elastic Path from Webapp-centric
to API-centric
Overview
(very) short Level 3 definition
Level 3 Misconceptions
Developing a Level 3 API
Level 3 REST (L3)
Links and Types
Not URLs (the antithesis of L3)
Not L2++
Like moving from Assembler to C
Named variables, not labeled memory addresses
Methods, not jump tables
More Who and What, less Where
REST is Mis-acronymed
Should be REality State Transfer
“Representations” are an intellectual snag that lead too quickly to type systems
L3 can only succeed when it models the real world
Most software abstractions take shortcuts:
Overload abstractions with multiple semantics
Reuse existing technical abstractions
Example: Products
What is a Product?
A Product Manager thinks of a set of options
A Customer thinks of something to put in their bag
In reality there is no such thing as a Product
Item: Something you buy and walk out with
Offering: Something that holds the possible options that lead to specific items
L3 is Hard
No HATEOAS Frameworks
All REST frameworks have Resources
None provide a way to define links between resources
L3 Clients are difficult to grok
…but not impossible. Talk to Drewz.
L3 APIs are Rare
Few Examples in the real world
“…no real facilities to support HATEOAS, a concept I feel is the unicorn of REST. Everyone thinks it’s wonderful but no one has ever actually seen it in the wild.”
–Lucis Ferre blogging about WebMachine
Elastic Path’s Unicorn
“L3 is HTTP used correctly”
HTTP is a transport protocol
L3 is an architectural style
Your server and client should be able to switch
to a different transport and succeed
“Content-Type is the Hypermedia Type”
Content-Type is an HTTP transport header
application/vnd.com.skynet.cyborg+json
…is just about as right as
application/com.warnerbrothers.featurefilm+mp4
X-Hypermedia-Type
Content-Type tells the client how the data is
serialized, not what type of data it is
Leave Content-Type to the transport layer
Put your media type in another header
Put it in your representation
“Stateless just means
Sessionless”
L3 requires one Source Of Truth
Stateless really means completely stateful
All State persisted in the backend
…not in the http session, or cookies, or client (duh)
Not in the query params either!
GET /search/books?keywords=Fear+Loathing
“Query params should pass data to a resource”
Data belongs in the representations, period
There are no universal business concepts
Example: pagination
?page=2&size=20
Resource has to understand what this means and
respond with an appropriate representation
It also may have different ways of providing pagination
“URIs should have User IDs in them”
Humans are not a resource
They own things like carts and orders and profiles
Their identity scopes their access
Authenticate them and pass their identities (and Roles) internally
BTW, anonymous users are people too
Build the Resource Model
Do NOT try to surface an existing API
Start with your existing User Interface
Use physical props
L3 works best when the resources are modeled
after the User’s experience of reality
Do this with a team, achieve unanimity
Basic Heuristics
1. A resource should have one responsibility
2. A resource has very little data and lots of links
3. “Secret Admirer” rule: A resource should not
know about the resources that link to it
Subresources
Subresources are rarely useful in L3
/carts/id/lineitems/id
Heuristic:
Is it an inseparable concept for both?
If no, then make it a separate resource
Connecting to Existing X
Cart Service
/carts/27
/carts/27/lineitems
/totals/carts/27
/prices/carts/27
orders/2/deliveries
The Dark Side of Links
The model is mostly links between resources
Downside: Chatty Cathy API
Your framework needs to provide a way to expand
related rels into a response
Example: Item
item
assets
prices
definition
availability
selections
add to cart form
Build the Hypermedia
Controls
Workflows are a series of state transitions in your process
Add to cart
Create profile
Deliver shipment
Authorize payment
These transitions are executed via hypermedia controls
What’s a Hypermedia
Control?
A design pattern for interacting with State
Can be multiple resources providing data and
actions to the control
Single entry point into the control
Numerous links inside the control
Form
The Government got it right
GET a /form
Fill it in
POST it to the action link
Selector
Like a radio button group or selection list
Set of links with choices
Each choice has:
definition
action
POST to action link
Needinfo
Link to indicate a related resource state is
incomplete. Interpreted as a transition blocker
Link points to a control to resolve the state
Example
Deliveryinfo required on an order to actually
deliver an order
Thank You All for a great
RESTFest 2012!
http://www.elasticpath.com