- The document summarizes implementing a workflow for ordering coffee at Starbucks using RESTful principles and hypermedia. It describes placing an order by POSTing to a URI, then receiving a link to add special instructions or pay by PUTting to the linked URIs. This models the workflow as state transitions between resources.

1. 22-10-2008
This Presentation Courtesy of the
International SOA Symposium
October 7-8, 2008 Amsterdam Arena
www.soasymposium.com
info@soasymposium.com
Founding Sponsors
Platinum Sponsors
Gold Sponsors Silver Sponsors
GET /Connected
Web Integration the Starbucks Way
Dr. Jim Webber
http://jim.webber.name
1

2. 22-10-2008
Roadmap
• A little Swedish
• Some home truths
– About Web Services and the Web
• Implementing Workflows
– The Starbuck’s example
• Q&A
Jag heter Jim und kommer du
England
• I like Web Services • I wrote this book,
– I am a MESTian at about WS-*
heart
• I like the Web
– I have sympathies
that lie with the
RESTafarians
2

3. 22-10-2008
Jag heter Jim und kommer du
England
• I like Web Services Mark Baker’s • I am “similarly
consulting company, minded”
– I am a MESTian at Coactus
heart
• I like the Web
– I have sympathies
that lie with the
RESTafarians
That’s me
Falling out of Love?
I hate WSDL. I wanna
• Two things: kick it squarely in the
nuts!
– WSDL
• It’s an XML IDL for RPC
• Therefore ill-suited for Internet scale Photo: Comedy Central
– All the superfluous WS-* standards and
politics
• Toolkits hide essential complexity
3

4. 22-10-2008
Why Web Services Rock My World
• Good Web Services/SOA are message-
oriented
– SSDL rules!
• Business processes tend to be message-
oriented
• End-to-end processing model
– Defined by SOAP, not WSDL!
• Composable model
– Ignore most of the WS-* stack
• Except WSDL because the toolkits embrace it  Photo: Comedy Central
Web Abuse
Tunnelling is
all a bunch of
• Two lo-fi approaches to tree-hugging
“Web” integration hippy crap!
– URI tunnelling
– POX
• Both models treat HTTP as a transport Photo: Comedy Central
– More or less
• Yet some of the Web jihadists don’t see this
• Both of these approaches overlay the Web
with their own (weak) models...
4

5. 22-10-2008
URI Tunnelling
• Web servers understand URIs
• URIs have structure
• Methods have signatures
• Can match URI structure to method
signature
• E.g.
– http://example.com/addNumbers?p1=10&p2=11
– intaddNumbers(inti, int j) { return i + j; }
URI Tunnelling Strengths
• Very easy to understand
• Great for simple procedure-calls
• Simple to code
– Do it with the servlet API, HttpListener,
IHttpHandler, Rails, whatever!
• Interoperable
– It’s just URIs!
• Cacheable – providing you don’t abuse
GET
5

6. 22-10-2008
URI Tunnelling Weaknesses
• Often used for brittle RPC
• Tight coupling, no metadata
• Lacks robustness
– Except for idempotent cases
• No metadata support
– Construct the URIs yourself, map them to the
function manually
POX Pattern
• POX uses XML in the HTTP request and
response to move a call stack between
client and server
• Web servers understand how to process
requests with bodies
• Hence we have another RPC mechanism
6

7. 22-10-2008
POX Strengths
• Simplicity – just use HTTP POST and XML
• Re-use existing infrastructure and
libraries
• Interoperable
– It’s just XML and HTTP POST
• Can use complex data structures
– By representing them in XML
POX Weaknesses
• Client and server must collude on XML
payload
– Tightly coupled approach
• No metadata support
– Unless you’re using a POX toolkit that
supports WSDL with HTTP binding (like WCF)
• Does not use Web for robustness
• Does not use SOAP + WS-* for robustness
7

8. 22-10-2008
RPC is Commonplace Today
• To err is human, to really mess things up you
need a computer
• To really, really mess things up you need a
distributed system
– “A Note on Distributed Computing”
• Bad Web Services and Web integration
have much in common
– It’s RPC!
– With latencies and nasty partial failure
characteristics
</rant>
8

9. 22-10-2008
Web Fundamentals
• To embrace the Web, we need to
understand how it works
• The Web is a distributed hypermedia
model
– It doesn’t try to hide that distribution from
you!
• Our challenge:
– Figure out the mapping between our problem
domain and the underlying Web platform
Why the Web was Inevitable
Tim Berners-Lee is a physicist
(Sir Tim is also a knight, but that’s not
important right now)
9

10. 22-10-2008
Why the Web was Inevitable
He lived in a hole in the ground
Underneath a big mountain
(in Switzerland)
Why the Web was Inevitable
And because he was a physicist (and
not yet a knight)...
...he only had a big atom-
smashing thing for
company
10

11. 22-10-2008
Why the Web was Inevitable
And for a lonesome physicist
stuck underground with smashed
up atoms for company...
...gopher just wasn’t
going to cut it!
The Web broke the rules
11

12. 22-10-2008
Web Characteristics
• Scalable
• Fault-tolerant
• Recoverable
• Secure
• Loosely coupled
• Precisely the same characteristics we
want in business software systems!
Tenets for Web-based Services
• Resource-based
– Rather than service-oriented (the Web is not MOM!)
• Addressability
– Interesting things should have names
• Statelessness
– No stateful conversations with a resource
• Representations
– Resources can be serialised into representations
• Links
– Resources
• Uniform Interface
– No plumbing surprises!
12

13. 22-10-2008
Resource Architecture
Consumer
(Web Client) Uniform Interface
(Web Server)
Logical Resources
Resource Representation
(e.g. XML document)
Physical Resources
Links
• Connectedness is good in Web-based
systems
• Resource representations can contain
other URIs
• Links act as state transitions
• Application (conversation) state is
captured in terms of these states
13

14. 22-10-2008
Describing Contracts with Links
• The value of the Web is its “linked-ness”
– Links on a Web page constitute a contractfor
page traversals
• The same is true of the programmatic
Web
• Use Links to describe state transitions in
programmatic Web services
– By navigating resources you change
application state
Links are State Transitions
14

15. 22-10-2008
Links as APIs
<confirm xmlns="..."> • Following a link
<link rel="payment"
href="https://pay"
causes an action to
type="application/xml"/>
occur
<link rel="postpone" • This is the start of a
href="https://wishlist" state machine!
type="application/xml"/>
</confirm>
• Links lead to other
resources which also
have links
• Can make this
stronger with
semantics
– Microformats
Microformats
• Microformats are an example of little “s”
semantics
• Innovation at the edges of the Web
– Not by some central design authority (e.g. W3C)
• Started by embedding machine-processable
elements in Web pages
– E.g. Calendar information, contact information,
etc
– Using existing HTML features like class, rel,
etc
15

16. 22-10-2008
Microformats and Resources
• Use Microformats to structure resources where
formats exist
– I.e. Use hCard for contacts, hCalendar for data
• Create your own formats (sparingly) in other
places
– Annotating links is a good start
– <link rel="withdraw.cash" .../>
– <link rel="service.post"
type="application/x.atom+xml"
href="{post-uri}" title="some title">
• The rel attribute describes the semantics of the
referred resource
We have a framework!
• The Web gives us a processing and metadata
model
– Verbs and status codes
– Headers
• Gives us metadata contracts or Web “APIs”
– URI Templates
– Links
• Strengthened with semantics
– Little “s”
16

17. 22-10-2008
Workflow
• How does a typical enterprise workflow look
when it’s implemented in a Web-friendly
way?
• Let’s take Starbuck’s as an example, the
happy path is:
– Make selection
• Add any specialities
– Pay
– Wait for a while
– Collect drink
Workflow and MOM
• With Web Services we
exchange messages
with the service
Order Drink
• Resource state is
hidden from view
Starbuck’s Service
Add Specialities
• Conversation state is
all we know
Order Confirmation
– Advertise it with
SSDL, BPEL
• Uniform interface, Pay
roles defined by SOAP
– No “operations” Coffee!
17

18. 22-10-2008
Web-friendly Workflow
• What happens if workflow stages are
modelled as resources?
• And state transitions are modelled as
hyperlinks or URI templates?
• And events modelled by traversing links
and changing resource states?
• Answer: we get Web-friendly workflow
– With all the quality of service provided by
the Web
Placing an Order
• Place your order by POSTing it to a well-
known URI
– http://example.starbucks.com/order
Starbuck’s Service
Client
18

19. 22-10-2008
Placing an Order: On the Wire
• Response
• Request 201 Created
Location:
POST /order HTTP 1.1
http://starbucks.example.org/
Host: starbucks.example.org order?1234
Content-Type: application/xml Content-Type: application/xml
Content-Length: ... Content-Length: ...
<order xmlns="urn:starbucks"> <order xmlns="urn:starbucks">
<drink>latte</drink> <drink>latte</drink>
</order> <link rel="payment"
If we have a (private) href="https://starbucks.examp
A link! Is this the
microformat, this can le.org/payment/order?1234"
start of an API?
become a neat API! type="application/xml"/>
</order>
Whoops! A mistake
• I like my coffee to taste like coffee!
• I need another shot of espresso
– What are my OPTIONS?
 Request  Response
OPTIONS /order?1234 HTTP 1.1 200 OK
Host: starbucks.example.org Allow: GET, PUT Phew! I can
update my
order, for now
19

20. 22-10-2008
Optional: Look Before You Leap
• See if the resource has changed since you
submitted your order
– If you’re fast your drink hasn’t been
prepared yet
 Request  Response
PUT /order?1234 HTTP 1.1 100 Continue
Host: starbucks.example.org I can still PUT this
Expect: 100-Continue resource, for now.
(417 Expectation
Failed otherwise)
Amending an Order
• Add specialities to you order via PUT
– Starbucks needs 2 shots!
Starbuck’s Service
Client
20

21. 22-10-2008
Amending an Order: On the Wire
• Request • Response
PUT /order?1234 HTTP 1.1 200 OK
Host: starbucks.example.org Location:
Content-Type: application/xml http://starbucks.example.org/o
Content-Length: ... rder?1234
Content-Type: application/xml
<order xmlns="urn:starbucks"> Content-Length: ...
<drink>latte</drink>
<additions>shot</additions> <order xmlns="urn:starbucks">
<link rel="payment" <drink>latte</drink>
href="https://starbucks.exampl <additions>shot</additions>
e.org/payment/order?1234" <link rel="payment"
type="application/xml"/> href="https://starbucks.exampl
</order> e.org/payment/order?1234"
type="application/xml"/>
</order>
Statelessness
• Remember interactions with resources are stateless
• The resource “forgets” about you while you’re not
directly interacting with it
• Which means race conditions are possible
• Use If-Unmodified-Since on a timestamp to
make sure
– Or use If-Match and an ETag
• You’ll get a 412 PreconditionFailed if you lost
the race
– But you’ll avoid potentially putting the resource into
some inconsistent state
21

22. 22-10-2008
Warning: Don’t be Slow!
• Can only make changes until someone
actually makes your drink
– You’re safe if you use If-Unmodified-Since
or If-Match
– But resource state can change without you!
 Request
 Response
PUT /order?1234 HTTP 1.1
409 Conflict
Host: starbucks.example.org
... Too slow! Someone else has
changed the state of my order
 Request  Response
OPTIONS /order?1234 HTTP 1.1 Allow: GET
Host: starbucks.example.org
Order Confirmation
• Check your order status by GETing it
Starbuck’s Service
Client
22

23. 22-10-2008
Order Confirmation: On the Wire
• Request • Response
GET /order?1234 HTTP 1.1 200 OK
Host: starbucks.example.org Location:
Content-Type: application/xml http://starbucks.example.org/orde
Content-Length: ... r?1234
Content-Type: application/xml
Content-Length: ...
<order xmlns="urn:starbucks">
<drink>latte</drink>
<additions>shot</additions>
Are they trying to tell me <link rel="payment"
something with hypermedia? href="https://starbucks.example.o
rg/payment/order?1234"
type="application/xml"/>
</order>
Order Payment
• PUT your payment to the order resource
https://starbucks.example.org/payment/order?1234
Starbuck’s Service
Client
New resource!
https://starbucks.example.org/payment/order?1234
23

24. 22-10-2008
How did I know to PUT?
• The client knew the URI to PUT to from the link
– PUT is also idempotent (can safely re-try) in case of failure
• Verified with OPTIONS
– Just in case you were in any doubt 
 Request  Response
OPTIONS /payment/order?1234 HTTP 1.1 Allow: GET, PUT
Host: starbucks.example.org
Order Payment: On the Wire
• Request • Response
PUT /payment/order?1234 HTTP 1.1 201 Created
Host: starbucks.example.org Location:
Content-Type: application/xml https://starbucks.example.or
Content-Length: ... g/payment/order?1234
Content-Type: application/xml
<payment xmlns="urn:starbucks"> Content-Length: ...
<cardNo>123456789</cardNo>
<expires>07/07</expires>
<name>John Citizen</name> <payment xmlns="urn:starbucks">
<amount>4.00</amount> <cardNo>123456789</cardNo>
</payment> <expires>07/07</expires>
<name>John Citizen</name>
<amount>4.00</amount>
</payment>
24

25. 22-10-2008
Check that you’ve paid
• Request • Response
GET /order?1234 HTTP 1.1 200 OK
Host: starbucks.example.org Content-Type: application/xml
Content-Type: application/xml Content-Length: ...
Content-Length: ...
My “API” has changed, <order xmlns="urn:starbucks">
because I’ve paid <drink>latte</drink>
enough now <additions>shot</additions>
</order>
What Happened Behind the Scenes?
• Starbucks can use the same resources!
• Plus some private resources of their own
– Master list of coffees to be prepared
• Authenticate to provide security on some
resources
– E.g. only Starbuck’s are allowed to view
payments
25

26. 22-10-2008
Payment
• Only Starbucks systems can access the record of payments
– Using the URI template: http://.../payment/order?{order_id}
• We can use HTTP authorisation to enforce this
 Response
 Request
GET /payment/order?1234 HTTP 1.1 401 Unauthorized
WWW-Authenticate: Digest
Host: starbucks.example.org realm="starbucks.example.org",
qop="auth", nonce="ab656...",
opaque="b6a9..."
 Request  Response
GET /payment/order?1234 HTTP 1.1 200 OK
Host: starbucks.example.org
Authorization: Digest username="jw" Content-Type: application/xml
realm="starbucks.example.org“ Content-Length: ...
nonce="..."
uri="payment/order?1234" <payment xmlns="urn:starbucks">
qop=auth <cardNo>123456789</cardNo>
nc=00000001 <expires>07/07</expires>
cnonce="..." <name>John Citizen</name>
reponse="..." <amount>4.00</amount>
opaque="..." </payment>
Master Coffee List
• /orders URI for all orders, only accepts GET
– Anyone can use it, but it is only useful for Starbuck’s
– It’s not identified in any of our public APIs anywhere, but the back-
end systems know the URI
 Response
 Request 200 OK
Content-Type: application/xml
GET /orders HTTP 1.1 Content-Length: ...
<?xml version="1.0" ?>
Host: starbucks.example.org <feed xmlns="http://www.w3.org/2005/Atom">
<title>Coffees to make</title>
<link rel="alternate"
href="http://example.starbucks.com/order.atom"/>
<updated>2007-07-10T09:18:43Z</updated>
<author><name>Johnny Barrista</name></author>
Atom feed! <id>urn:starkbucks:45ftis90</id>
<entry>
<link rel="alternate" type="application/xml"
href="http://starbucks.example.org/order?1234"/>
<id>urn:starbucks:a3tfpfz3</id>
</entry>
...
</feed>
26

27. 22-10-2008
Finally drink your coffee...
Source: http://images.businessweek.com/ss/06/07/top_brands/image/starbucks.jpg
What did we learn from Starbucks?
• HTTP has a header/status combination for every occasion
• APIs are expressed in terms of links, and links are great!
– APP-esque APIs
• APIs can also be constructed with URI templates and
inference
– But beware tight coupling outside of CRUD services!
• XML is fine, but we could also use formats like Atom, JSON
or even default to XHTML as a sensible middle ground
• State machines (defined by links) are important
– Just as in Web Services…
27

28. 22-10-2008
Summary
• Web-based services are about state
machines
– The HATEOAS constraint from REST
• Use Web for massive scalability, fault
tolerance
– If you can tolerate higher latencies
• The Web is now starting to feel the love
from middleware vendors too – beware!
Starbucks Written Up @ InfoQ
http://www.infoq.com/articles/webber-rest-workflow
28

29. 22-10-2008
Questions?
Blog:
http://jim.webber.name
GET /Connected
Jim Webber
Savas Parastatidis
Ian Robinson
Coming Q1 2009…
29