so you want to do rest · the rest uniform interface identiﬁcation of resources resource...

© 2012 innoQ Deutschland GmbH

So you want to do REST …Stefan Tilkov | @stilkov | Java User Group Dortmund

Wednesday, August 29, 12

© 2006-2012 innoQ Deutschland GmbH 2

Stefan [email protected]

@stilkovhttp://heise.de/developer/podcast/

innoQ Deutschland GmbH

http://www.innoq.com

Krischerstr. 10040789 Monheim am RheinGermanyPhone: +49 2173 3366-0

innoQ Schweiz GmbH

[email protected]

Gewerbestr. 11CH-6330 ChamSwitzerlandPhone: +41 41 743 0116



REST Intro


REpresentational State Transfer


The REST Uniform Interface

identificationof resources

resource manipulation through representations

hypermedia as the engine of application state

self-descriptive messages



http://example.com/orders?year=2008

http://example.com/customers/1234

http://example.com/orders/2007/10/776654

http://example.com/products/4554

http://example.com/processes/sal-increase-234











GET /customers/1234Host: example.comAccept: application/vnd.mycompany.customer+xml

...

GET /customers/1234Host: example.comAccept: text/x-vcard

begin:vcard...end:vcard







23







23





Stop WorryingAbout URI Design


The REST Uniform Interfaceidentificationof resources




GET /service/customers/1234 HTTP 1.1Host: www.example.comUser-Agent:

XYZ 1.1Accept:

text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8Keep-Alive:

300Connection:

keep-aliveIf-Modified-Since:

Fri, 02 Oct 2009 16:47:31 GMTIf-None-Match:

"600028c-59fb-474f6852c9dab"Cache-Control:

max-age=60

HTTP/1.1 200 OKDate:

Sun, 04 Oct 2009 19:36:25 GMTServer:

Apache/2.2.11 (Debian)Last-Modified:

Fri, 02 Oct 2009 16:47:31 GMTEtag:

"600028c-59fb-474f6852c9dab"Cache-Control: max-age=300Accept-Ranges:

bytesVary:

Accept-EncodingContent-Encoding:

gzipContent-Length:

7160Keep-Alive:

timeout=15, max=91Connection:

Keep-AliveContent-Type:

application/xml

...

StandardMethod

Media Type

Data

Control DataVisibilityWednesday, August 29, 12

getOrderDetails()

updateQuote()

cancelSubscription()

findMatchingBid()initiateProcess()

submitApplicationData()

listAuctions()getUsers()


updateQuote() cancelSubscription()

findMatchingBid()

initiateProcess()submitApplicationData()

listAuctions()getUsers()

getOrderDetails()

GET

PUT

POST

DELETE


interface Resource { Resource(URI u) Response get() Response post(Request r) Response put(Request r) Response delete()}

generic

specific

class CustomerCollection : Resource { ... Response post(Request r) { id = createCustomer(r) return new Response(201, r) } ...}

Any HTTP client(Firefox, IE, curl, wget)

Any HTTP server

Caches

Proxies

Google, Yahoo!, MSN

Anything that knows your app


© 2006-2012 innoQ Deutschland GmbH

many very few(one per service)

many

The Options Triangle

15Wednesday, August 29, 12


very few(fixed)

many

many

The Options Triangle



Mapping ExamplesgetFreeTimeSlots(Person) →GET /people/st/timeslots?state=free

rejectApplication(Application)→POST /rejections↵ http://...↵ Unsuitable for us!

performTariffCalculation(Data)

→POST /contracts↵ Data←Location: http://.../contracts/4711 →GET /contracts/4711/tariff←Result

shipOrder(ID) →PUT /orders/0815/status↵ shipped

shipOrder(ID) [variation]→POST /shipments↵ Data←Location: http://.../shipments/4711



Implementing Servers



Libraries & Frameworks

JAX-RS (Jersey, RESTEasy, CXF, Wink)

Restlet

Sling

Vert.x, Netty, Grizzly

...

19

Spring MVC

Play!

Servlets

Spark

Sitebricks



Implementing Clients




JAX-RS 2.0 (Jersey, RESTEasy, CXF, Wink)

Restlet

AsyncHttpClient

Play! Client

Spring RestTemplate

Apache HTTPComponents



Implementation Anti-Patterns



Client-side URI Construction

String baseUri = "http://example.com/";String uri = baseUri + "/services/ordermgmt/customers/" + customerId + "/orders/" + orderId + ".xml";Response r = request(GET, uri);



Domain Model Exposure



//// This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference Implementation, vJAXB 2.1.10 in JDK 6 // See http://java.sun.com/xml/jaxb // Any modifications to this file will be lost upon recompilation of the source schema. // Generated on: 2011.06.15 at 01:43:47 PM CEST //

package generated;

import javax.xml.bind.annotation.XmlAccessType;import javax.xml.bind.annotation.XmlAccessorType;import javax.xml.bind.annotation.XmlAttribute;import javax.xml.bind.annotation.XmlElement;import javax.xml.bind.annotation.XmlSchemaType;import javax.xml.bind.annotation.XmlType;import javax.xml.datatype.XMLGregorianCalendar;

@XmlAccessorType(XmlAccessType.FIELD)@XmlType(name = "bookdata", propOrder = { "author", "title", "genre", "price", "publishDate", "description"})public class Bookdata {

@XmlElement(required = true) protected String author; @XmlElement(required = true) protected String title; @XmlElement(required = true) protected String genre; protected float price; @XmlElement(name = "publish_date", required = true) @XmlSchemaType(name = "dateTime") protected XMLGregorianCalendar publishDate; @XmlElement(required = true) protected String description; @XmlAttribute protected String id;

/** * Gets the value of the author property. * * @return * possible object is * {@link String } * */ public String getAuthor() { return author; }

/** * Sets the value of the author property. * * @param value * allowed object is * {@link String } * */ public void setAuthor(String value) { this.author = value; }

/** * Gets the value of the title property. * * @return * possible object is * {@link String } * */ public String getTitle() { return title; }

/** * Sets the value of the title property. * * @param value * allowed object is * {@link String } * */ public void setTitle(String value) { this.title = value; }

/** * Gets the value of the genre property. * * @return * possible object is * {@link String } * */ public String getGenre() { return genre; }

/** * Sets the value of the genre property. * * @param value * allowed object is * {@link String } * */ public void setGenre(String value) { this.genre = value; }

/** * Gets the value of the price property. * */ public float getPrice() { return price; }

/** * Sets the value of the price property. * */ public void setPrice(float value) { this.price = value; }

/** * Gets the value of the publishDate property. * * @return * possible object is * {@link XMLGregorianCalendar } * */ public XMLGregorianCalendar getPublishDate() { return publishDate; }

/** * Sets the value of the publishDate property. * * @param value * allowed object is * {@link XMLGregorianCalendar } * */ public void setPublishDate(XMLGregorianCalendar value) { this.publishDate = value; }

/** * Gets the value of the description property. * * @return * possible object is * {@link String } * */ public String getDescription() { return description; }

/** * Sets the value of the description property. * * @param value * allowed object is * {@link String } * */ public void setDescription(String value) { this.description = value; }

/** * Gets the value of the id property. * * @return * possible object is * {@link String } * */ public String getId() { return id; }

/** * Sets the value of the id property. * * @param value * allowed object is * {@link String } * */ public void setId(String value) { this.id = value; }

}

Schemai!cation

Magic



REST Principles revisited

26

Identi!able resources

Uniform interface

Resource representations

Hypermedia as the engine of application state

Stateless communication



Links, we have links


© 2006-2012 innoQ Deutschland GmbH 28

Client

Server



“Named” Links

29

Resource relationships in representations

Independence from URI design

Possible “De-Co-Location”



Service Documents

30

Document with links to “entry point” resources

Can be consumer-speci!c

Additional “cheap” decoupling

Federated if necessary



Service documents



Example

32


http://om.example.comhttp://om.example.comhttp://om.archive.com/orders/http://om.archive.com/orders/


UDDIPublicationn save_bindingn save_businessn save_servicen save_tModeln delete_bindingn delete_businessn delete_publisherAssertionsn delete_servicen delete_tModeln add_publisherAssertionsn set_publisherAssertionsn get_assertionStatusReportn get_publisherAssertionsn get_registeredInfo

Inquiryn !nd_bindingn !nd_businessn !nd_relatedBusinessesn !nd_servicen !nd_tModeln get_bindingDetailn get_businessDetailn get_operationalInfon get_serviceDetailn get_tModelDetail

Dead as

a parro

t



Link styles

34



Resource Links

Inherited from your domain model

Links between collection- and primary resources

Links for self-references

Make even implicit relationships explicit to prevent client-side assumptions



State Transition Links

Determine the possible client actions

Distinction from resource links is leaky since every link acts as state transition



Link Relations

rel Attribute determines link semantics

not consistently standardized

‣ HTML: http://www.w3.org/TR/html401/types.html#type-links

‣ Atom: http://www.iana.org/assignments/link-relations/link-relations.xhtml

Be aware of naming collisions while inventing your own rel values

37


Link Relations

38

received


http://om.example.comhttp://om.example.comhttps://paypalhttps://paypal


Link Header (RFC 5988)

strive for standardizing link relations

representation independent

can use URIs as rel values to prevent name collisions

relative URIs default to IANA base-uri

39

HTTP/1.1 200 OK Link: ; rel="prev" Link: ; rel="next"

Link: ; rel="prev" Link: ; rel="http://www.iana.org/ assignments/relation/prev"


http://om.example.com/orders/?page=2http://om.example.com/orders/?page=2http://om.example.com/orders/?page=4http://om.example.com/orders/?page=4http://om.example.com/orders/?page=2http://om.example.com/orders/?page=2http://om.example.com/orders/?page=4http://om.example.com/orders/?page=4http://www.iana.orghttp://www.iana.org


Implementing Webapps




JAX-RS (Jersey, RESTEasy, CXF, Wink)

Restlet

Sling

...

41

Spring MVC

Play!

Servlets

Spark

Sitebricks



The Human Web



Resources

Pretty URLs

Bookmarks

Collaboration

Caching

Hypermedia



Web Sitesvs.

Web Applications



Using the Webvs.

Abusing the Web



There should be no applications



Customer

Order Delivery

ProductCustomerList

ProductCatalog

CustomerView

OrderEntryForm ProductMaintenanceForm



Customer

Order

Delivery Product

CustomerList

ProductCatalog

Rating

«interface»Resource

CustomerViewOrderEntryForm

ProductMaintenanceForm



What’s in an app?



Browser

Server AClient A

Server BClient B



Browser

Server A

Server B

Client Portal



Browser

Server A

Server B

Resource 1

Resource 2

Resource n

Representation 1

Representation 2

Representation n

......



Browser

HTML Page

Backend 1

UI 1

FrontendServer

UI 2

Server-side integration

Backend 2

Examples:ESI-CachesSSIPortal Server



Browser

HTML Page

Backend 1

UI 1

UI 2

Client-side integration

Backend 2

Examples:AJAXProprietary Frameworks



Multiple tabs

Multiple windows

Menus

Bookmarks

Personalization

UI Integration



My browser is my portal



Browser

HTML Page 1

Links

Backend 1

Backend 2

AssetServer

HTML Page 2

CSS



Choosing a Web framework



How much HTTP would you like with that?



Server-side component-based

JSF

ASP.NET

Wicket

Tapestry

Vaadin



Request/Response-oriented

Struts

Play!Grails

Rails

ASP.NET MVC

PHPDjango

Spring MVCSpark

Sitebricks



Rich-client

Applets

JavaFXGWT

Silverlight

Flash/Flex

EchoZK

Meteor

Backbone.js



Linkable and “pretty” URIs

GET/POST di!erentiation

Support for caching

Full control over HTML

1 Resource, n Views

Request/Response Frameworks



“But what about statefulWeb applications?”



Server

Client 1

Client 2State Client 1

State Client 2

Server State

R1R2

Rn

Representation

R1

R2

Turn session state …



Server

Client 1

C1 C1

Client 2

C2

State Client 1

State Client 2

Server State

Representation

R1 R2

RnC2

C2

C2

C1C1

R2

R1

… into client or resource state



Browser Server

HTML Page

Label

Label

Label

Label

Label

Label

Label

Label

Submit



Browser Server

Label

Label

Label

Next

Label

Label

Label

Next

Label

Label

Finish

SessionState



Browser

Server

Label

Label

Label

Next

Label

Label

Label

Next

Label

Label

Finish

HTML Page

Label

Label

Label

Label

Label

Label

Label

Label

Submit

Client State



From server to clientServer Client

Server-sideComponents

ROCASingle

Page Apps

Flash

Silverlight

Applets

…



ROCAhttp://roca-style.org/



MUSTPhoto under CC by mendhak



1. REST principles

2. Server-side application logic

3. No redundant logic

4. Non-browser access

5. Server sends structured HTML

6. Progressive enhancement/unobtrusive JavaScript

7. No dynamic JavaScript



SUGGESTED

Photo under CC by Sarah Reid



1. Additional representations(JSON, XML, ...)

2. Authentication via HTTP mechanisms, cookies if unavoidable

3. Use of HTML 5 history API



VIOLATIONS



1. Broken accessibility

2. Session state

3. Broken back/forward/refresh

4. No bookmarks/links

5. JS “engines” in client

6. Server-side dependency on JS-generated markup

7. Hashbangs et al.



Summary



Don’t be afraidof Web technologies



REST is mainstream & becoming widely adopted



REST is not a stylefor web services only



Thank you!

Q&AStefan [email protected]://www.innoq.com/blog/st/@stilkovPhone: +49 170 471 2625

innoQ Deutschland GmbH

http://www.innoq.com

Krischerstr. 10040789 Monheim am RheinGermanyPhone: +49 2173 3366-0

innoQ Schweiz GmbH

[email protected]

Gewerbestr. 11CH-6330 ChamSwitzerlandPhone: +41 41 743 0116

mailto:[email protected]:[email protected]://www.innoq.comhttp://www.innoq.com