REST in Practice - Part II

7/28/2019 REST in Practice - Part II

1/53

REST in Practice

Part II

Centro de InformticaUniversidade Federal de Pernambuco

Vanilson Burgio

[www: vanilson.com] - [email: [email protected] ]August-2011


2/53

2

Part of this presentation was based on the high quality

material gently provided by Dr. Jim Webber, author of thebook REST in Practice: Hypermedia and Systems

Architecture, for educational purposes.


3/53

Agenda

Discussion

Research Activity

Tutorial

REST with Java (JAX-RS) using Jersey

Hypermedia and RESTFul Services

3


4/53

Research Activity

Compare:

REST Vs SOAP

REST Vs SOA

REST Vs WS-*


5/53

Tutorial: REST with Java (JAX-RS)using Jersey


6/53

Java, REST and Jersey

JAX-RS (The Java API for RESTful Web Services) Java standard REST support

Annotations to define the REST relevance of classes

In "web.xml" you will register a servlet provided by Jersey

also define the path under which your REST web application will be available

Open Source

Reference

Implementation for

building RESTful Web

services

http://your_domain:port/display-name/url-pattern/path_from_rest_class


7/53

First example simple resource

Defining a simple resource accessing its different representations using HTTP Accept request header

Our URL pattern: /rest/*

TODO:

Modify web.xml

TitleResource.java

http://localhost:8080/IN1163/rest/title

Multiple resource representations

addressed by a single URI

XML

representation

HTML

representation

TEXT

representation

title

resourcehttp://localhost:8080/IN1163/rest/title

Social

Machines - IN1163 -

2011.2

Social

Machines - IN1163 -

2011.2

Social Machines -

IN1163 - 2011.2

http://localhost:8080/IN1163/rest/title

titleSocial Machines - IN1163 -

2011.2


8/53

First example simple resource

Defining na Application Client to manipulate the resource Creating a web resource

ClientConfig config = new DefaultClientConfig();

Client client = Client.create(config);

WebResource webResource = client.resource().path(").path();

Send a GET

webResource.accept().get()

TODO: TitleClient.java


9/53

JAXB

Restful webservices and JAXB JAX-RS supports the automatic creation of XML and JSON via JAXB

@XmlRootElement

TODO: Lesson.java

Analyse class: OneLessonResource.java

Test: http://localhost:8080/IN1163/rest/oneLesson


10/53

CRUD (Create, Read, Update, Delete) restful

web service

Existing class: LessonDao.java

TODO

List lessons on browser (LessonsResource.java)

Count lessons (LessonsResource.java)

Create a new lesson from a HTML form LessonsResource.java

create_lesson.html

Get an specific lesson (... /rest/lessons/1)

LessonResource

LessonsResource.java

Delete a lesson

LessonsClient


11/53

Hypermedia and RESTfulServices


12/53

Revisiting Resource Lifetime

On the Web, the lifecycle of a single resource ismore than:

Creation

Updating

Reading Deleting

Can also get metadata

About the resource

About its (subset of) the verbs it understands

And as we see, resources tell us about otherresources we might want to interact with


13/53

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


14/53

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 inprogrammatic Web services

By navigating resources you change application state

Hypermedia formats support this

Allow us to describe higher-order protocols which sitcomfortably atop HTTP

Hence application/vnd.restbucks+xml


15/53

Links are State Transitions


16/53

Links as APIs

Following a link causes

an action to occur

This is the start of a

state machine! Links lead to other

resources which also

have links

Can make this strongerwith semantics

Microformats


17/53

Richardson Model Level 3

Lots of URIs that

address resources

Embraces HTTP as an

application protocol

Resource

representations and

formats identify other

resources

Hypermedia at last!


18/53

Protocol REST

Protocol REST Focus on media types as contracts

Protocol state transitions

DAPs Domain Application Protocols


19/53

Workflow and MOM

With Web Services weexchange messages withthe service

Resource state is hiddenfrom view

Conversation state is allwe know Advertise it with SSDL,

BPEL

Uniform interface, rolesdefined by SOAP No operations


20/53

Hypermedia Describes Protocols!

Links declare next valid steps Following links and interacting with resources changes

application state

Media types with links define contracts Media type defines processing model

Links (with microformats) describe state transitions

Dont need a static contract description No WSDL, no WADL

This is HATEOAS!

So lets see how we order a coffee at Restbucks.com Based on:

http://www.infoq.com/articles/webber-rest-workflow


21/53

Workflow

How does a typical enterprise workflow lookwhen its implemented in a Web-friendly way?

Lets take Restbucks ordering service as an

example, the happy path is: Make selection

Add any specialities

Pay

Wait for a while

Collect drink


22/53

Static Interface and State Transitions

payment

expected

preparing ready completed5 6

1

h p://restbucks.com/ordernew order

(create resource) 1POST

h p://restbucks.com/order/1234order cancelled (only if

state is at payment

expected)3DELETE

h ps://restbucks.com/payment/1234 Payment accepted 4PUT

h p://restbucks.com/receipt/1234Conclude the ordering

process 6DELETE

Barista prepared order 5

cancelled

h p://restbucks.com/order/1234update order (only if state is

at payment expected)2POST

2

4

3

h p://restbucks.com/order/1234return latest representa on

of the resourceGET

Transi ons ini ated

by consuming applica ons

Events causing

state transi ons

Business logic


23/53

Place an Order

POST to a well-known URI

http://restbucks.com/order

Client

RestbucksService


24/53

Placing an Order

RequestPOST /order HTTP/1.1

Content-Type: application/vnd.restbucks+xml

Accept: application/vnd.restbucks+xml

Host: restbucks.com

Connection: keep-alive

Content-Length: 283

semi

largelatte

takeaway


25/53

Placing an Order

ResponseHTTP/1.1 201 Created

server: grizzly/1.8.1

Location: http://restbucks.com/order/1234


Content-Length: 1039

Date: Wed, 03 Mar 2010 20:58:03 GMT

semi

large

latte

takeaway

2.0

unpaid


26/53

Confirm the Order

GET from the rel=self URI http://restbucks.com/order/1234

Client

RestbucksService


27/53

Confirm the Order

RequestGET /order/1234 HTTP/1.1


Host: restbucks.com



28/53

Confirm the Order

ResponseHTTP/1.1 200 OK

Location: http://restbucks.com/order/1234


Content-Length: 911

Date: Sun, 06 Sep 2009 06:51:22 GMT

semi

largelatte

takeaway

2.0

unpaid


29/53

Change the Order

POST new order to service-generated URI http://restbucks.com/order/f932f92d

Client

RestbucksService


30/53

POST? Not PUT?

PUT expects the whole resource state to bepresented in the request

But our clients arent responsible for generating

cost or status elements

PATCH would be better

It allows us to send diffs, but isnt part of the

standard yet

So POST is our only option Compare this to our CRUD protocol earlier


31/53

Change the Order

RequestPOST order/1234 HTTP/1.1



Host: restbucks.com

Connection: keep-aliveContent-Length: 288

semilarge

cappuccino

takeaway

No service-

generatedcontent


32/53

Change the Order

ResponseHTTP/1.1 200 OKLocation: http://restbucks.com/order/1234


Content-Length: 916

Date: Sun, 06 Sep 2009 06:52:22 GMT

semi

large

cappuccino

takeaway

2.0

unpaid


33/53

Statelessness

Remember interactions with resources arestateless

The resource forgets about you while yourenot 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

Youll get a 412 PreconditionFailed ifyou lost the race But youll avoid potentially putting the resource into

some inconsistent state


34/53

Warning: Dont be Slow!

Can only make changes until someone actuallymakes your drink

Youre safe if you use If-Unmodified-Since orIf-Match

But resource state can change without you!

RequestPUT /order/1234 HTTP 1.1

Host: restbucks.com

...

Response409 Conflict

Too slow! Someone else haschanged the state of my order

RequestOPTIONS /order/1234 HTTP 1.1

Host: restbucks.com

ResponseAllow: GET


35/53

What if we want to cancel?

DELETE order at order URI http://restbucks.com/order/1234

Client

RestbucksService


36/53

What if we want to cancel?

RequestDELETE /order/1234HTTP/1.1

Host: restbucks.com


ResponseHTTP/1.1 200 OKContent-Type: application/vnd.restbucks+xml

Date: Sun, 06 Sep 2009 06:53:22 GMT


37/53

Order Payment

PUT to service-generated payment URI http://restbucks.com/payment/1234

Client

RestbucksService


38/53

Why PUT this time?

Its idempotent Safe to repeat in the event of failures

For all $ transactions, prefer idempotent verbs


39/53

Order Payment

RequestPUT /payment/1234 HTTP/1.1Content-Type: application/vnd.restbucks+xml


Host: restbucks.com


Content-Length: 287

2.0

Michael Farraday

11223344

12

12


40/53

Order Payment

ResponseHTTP/1.1 201 Created


Location: http://restbucks.com/payment/1234


Content-Length: 650

Date: Wed, 03 Mar 2010 20:58:03 GMT

2.0Michael Farraday

11223344

12

12


41/53

What if we want to cancel now?

RequestDELETE /order/1234 HTTP/1.1

Host: restbucks.com


ResponseHTTP/1.1 405 Method Not AllowedAllow: GET


Content-Length: 0

Date: Sun, 06 Sep 2009 07:43:29 GMT


42/53

Grab a Receipt

GET service-generated receipt URI http://restbucks.com/receipt/1234

Client

RestbucksService


43/53

Grab a Receipt

RequestGET /receipt/1234 HTTP/1.1


Host: restbucks.com


44/53

Grab a Receipt

RequestHTTP/1.1 200 OK



Content-Length: 384

Date: Wed, 03 Mar 2010 20:58:03 GMT

2.0

2010-03-03T21:58:03.834+01:00


45/53

Poll until the orders ready

GET from the rel=order URI http://restbucks.com/order/f932f92d

Client

RestbucksService


46/53

Polling for a ready order on the wire

RequestGET /order/1234 HTTP/1.1

Host: restbucks.com



47/53

Orders ready, take the receipt and

walk away




Content-Length: 534

Date: Wed, 03 Mar 2010 20:58:03 GMT

semi

largecappuccino

takeaway

2.0

ready


48/53

Complete the Order

DELETE order at rel=receipt URI http://restbucks.com/receipt/1234

Client

RestbucksService


49/53

Complete the Order

RequestDELETE/receipt/1234 HTTP/1.1

Host: restbucks.com



50/53

Complete the Order



Content-Type: application/xml

Content-Length: 393

Date: Wed, 03 Mar 2010 20:58:03 GMT

semi

large

cappuccino

takeaway

2.0

taken

No HypermediaControls


51/53

Source: http://images.businessweek.com/ss/06/07/top_brands/image/starbucks.jpg


52/53

What did we learn from Restbucks?

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


53/53

References

REST in Practice Hypermedia and Systems ArchitectureJim Webber, Savas Parastatidis, Ian Robinson

Published by OReilly, 2010

REST in Practice - A Tutorial on Web-based Services

Jim Webber, Savas Parastatidis, Ian Robinson

Presentation for Universities, shared by Jim Webber

Somes slides adapted from a presentation for Universities (REST in Practice - A

Tutorial on Web-based Services) shared by Jim Webber

[http://jim.webber.name]

A Brief Introduction to REST http://www.infoq.com/articles/rest-introduction

REST with Java (JAX-RS) using Jersey Tutorial: http://bit.ly/ctZAhU

REST in Practice - Part II

Documents

Transcript of REST in Practice - Part II