You are on page 1of 76

REST in Practice Part I

Centro de Informática Universidade Federal de Pernambuco

Vanilson Burégio
[www:] ‐ [email: ] A August t‐2011

Part of this presentation was based on the high quality material gently provided by Dr. Jim Webber, author of the book “REST in Practice: Hypermedia and Systems Architecture”, for educational purposes.


• • • • • • Motivation Web Architecture Introduction to REST Practical Example Web Tunneling CRUD web b services i


 combine.Motivation • The web has radically transformed the way we produce and  share information – International ecosystem of application and sevices • We can search. cache and archive  information that underpins today’s digital society! • Today s Web is in large part the HUMAN WEB Today’s – Human users are the direct consumers of services offered by the  majority of web applications • How we might apply the Web’s underlying architectural  principles i i l  to t  building b ildi  distributed di t ib t d systems t  (enterprise ( t i   applications)?  4 . aggregate. replicate. transform.

  research  government. government  social. research. social  and individual interests • Anarchic architecture: thousands  of simple. small‐scale interactions between agents and resources that use the founding  technologies h l i  of f HTTP and d the h  URI 5 .Web Architecture • A caotic place: mix of business.

Web Architecture • Principles and technologies – URI and resources playing a  leading  role – Caches for scalability – Services boundaries support • Isolation so at o  and a d Independent depe de t evolution e o ut o  o of  functionality • encouraging loose coupling 6 .

7 .etc • Together. content delivery networks. these elements support the deployment of a  planetary l t ‐scale l  network t k of f systems t without ith t resorting ti  to t   intricate object models or complex middleware solutions.  proxies.Web As an Application Platform • The most pervasive middleware!! – D Despite it the th amount t of f research h and d development d l t that th t has h  gone  into several platforms. none of them has managed to become as  pervasive as the Web is today • Web’s Middleware: set of widely deployed and  commoditized elements: web servers that host resources. caches.

... p y. . Why Why? ? • The Web as a platform is the result of its architectural  simplicity. 8 . the use of a widely y implemented p  and agreed g ‐upon p   protocol (HTTP).Web As na Application Platform Platform. and the pervasiveness of common  representation formats • Technology Support – It is supported by several development technologies and platforms • Scalability and Performance – global deployment of networked applications • Loose Coupling – Services change without notification – There is no explicity mechanisms to support information integrity – HTTP uses status code. Broken links....

Web As na Application Platform Platform. XML and other formats are all just resources representation 9 . Why Why? ? • Business Processes – St States t  of f a process modeled d l d as resources – None of the work to capture business processes (BPEL.) really embraced the Web’s achitectural principals • Consistency and Uniformity – Principle of uniformity: HTML. .. *WS‐ Choreography.....

H How t  building to b ildi computer t systems t  in i   a web‐centric way (embracing the web’s architectural principals)? principals)? 10 .

But . what does it mean mean? ? 11 .REST!!  But.

REST ‐  ‐ REpresentational State Transfer • REST is an Architectural Style – REST is a set of principles that define how Web standards. are supposed to be used • REST isn’t… – Just pretty URIs – Just XML or JSON – URI t templates l t – AJAX applications 12 . such as  HTTP and URIs.

Key REST Principles • If you adhere to REST principles while designing your  application  you will end up with a system that exploits the  application. Web’s architecture to your benefit • Key Principles – – – – Identification d f of f resources (URI) ( ) Manipulation of resources through REPRESENTATIONS Hypermedia as the engine of application state Uniform Interface constraint 13 .

 from a document or  video clip to a business process or device • Al Almost t anything thi  can be b  modeled d l d as a resource and d  then made available for manipulation over the  network t k 14 ..Thinking in Resources Resources... • Resources are the fundamental building blocks of  web b‐based b d systems – A resource is anything we expose to the Web.. .

Resources and identifiers • To use a resource we need both to be able to identify it on the network and to have some  means of manipulating it The web provides the Uniform Resource Identifier (URI) – – The relationship between URIs and resources is many‐to‐one There’s no limit on the number of URIs that can refer to a resource. and it is in fact quite common  for a resource to be identified by numerous URIs • • A URI takes the form <scheme>:<scheme‐specific‐structure> – The scheme defines how the rest of the identifier is to be interpreted 15 .

Resources and identifiers Terms used on the Web to refer to identifiers 16 .

 or JPEG. MP3.  JSON.Resource Representations • • • Each identifier is associated with one or more representations A Representation is a transformation or a view of a resource resource’s s state at an instant  in time Resource representation formats – The resource’s view is encoded in one or more transferable formats. XML. plain text. such as XHTML. Atom. comma‐separated values. they never access the underlying resource directly Human‐friendly machine‐friendly 17 . • The e Web eb does not ot support suppo t po pointers! te s!  – Access to a resource is always mediated by way of its representations web components exchange  representations.

json Consumers can negotiate for specific representation  formats using HTTP Accept request header with a list  of f media di  types they’re h ’  prepared d to process Multiple resource representations addressed by a single URI 18 .com/order.xml or .json to indicate a preferred format  http://restbucks.xml or http://example.Resource Representations • Content negotiation mechanism – There is a misconception that different resource representations  should each have their own URI (notion popularized by the Rails  framework) • resource terminate URIs with .org/order.

  – The difference from traditional state machines: the possible states  and the transitions between them are not known in advance. just like a state machine.  Instead  as the application reaches a new state. state  the next possible  transitions are discovered.Hypermedia as the engine of application  state (HATEOAS) (HATEOAS) • The principle: Use links to refer to identifiable resources  wherever possible – A distributed application makes forward progress by transitioning  from one state to another. Instead. – Link Things to each other… 19 .

Hypermedia as the engine of application  state (HATEOAS) (HATEOAS) • REST describes the Web as a distributed hypermedia  application whose linked resources communicate by  exchanging representations of resource state – Links act as embedded identifiers of the states to which the  application can transition 20 .

HEAD  TRACE TRACE.Uniform Interface Constraint • The set of verbs supported by HTTP—GET. DELETE. and PATCH—forms a sufficiently  general‐purpose protocol to support a wide range of solutions • Use standard Methods – – – – GET: retrieve information. OPTIONS.  OPTIONS  HEAD. POST. possibly cached PUT: Update or create with known ID POST: Create or append sub‐resource DELETE: (logically) (l i ll ) remove 21 . CONNECT CONNECT. PUT.

Example: Example : online shop • Functionalities – list orders – – – – – list customers get order details List orders for customer Delete customer Add order item –g get customer details – – – – – Update customer Cancel order Add customer Submit order Update order Which [web] ] services could be created created? ? 22 .

Example: online shop • One p possibility: y  two Services Thinking g in REST  principles.. principles . How to design in terms of resources with an uniform interface? 23 ....

How to design with an uniform interface? • The set of verbs supported by HTTP forms a sufficiently general‐ purpose protocol to support a wide range of solutions GET: retrieve information. possibly cached PUT: Update or create with known ID     POST: Create or append sub‐resource DELETE: (logically) remove Which resources could be considered?  How to map the f functionalities? i li i ? 24 .

Approach differences • The first approach Many Many Very few (one by service) 25 .

Approach differences • The second approach Many Very few (FIXED) Many 26 .

.Richardson maturity model for the Web..  not just REST. • REST is a brilliant  architectural style • But the Web allows for  more than j just RESTful systems • There’s a spectrum of  maturity of service styles – From completely bonkers  to completely RESTful • We’ll use the Richardson  maturity model to frame  these kinds of discussions – Level 0 to Level 3 – Web‐ignorant to RESTful! .

Web Tunnelling .

Web Tunnelling • Web Services tunnel SOAP over HTTP – Using the Web as a transport only – Ignoring many of the features for robustness the  Web has built in • Many Web people do the same! – URI tunnelling. POX approaches are the most  popular styles on today’s Web – Worse than SOAP! But they y claim to  • Less metadata! be “lightweight”  and RESTful .

Richardson Model Level 1 • Lots of URIs – But really has a more  level 0 mindset • Doesn’t understand  HTTP – Other than as a  transport • No hypermedia .

} .URI Tunnelling Pattern • • • • Web servers understand URIs URIs have structure Methods have signatures Can match URI structure to method signature‐location=to‐go service method arguments maps to public OrderConfirmation PlaceOrder(Order  order) { ..

On The Wire .

ToString().OrderId. string response = string. response = "OrderId=" + orderConfirmation. if (order != null) { // Process the order by calling the mapped method var orderConfirmation = RestbucksService.PlaceOrder(order).Empty. } } .Response.Write(response).Server‐Side URI Tunnelling Example public void ProcessGet(HttpListenerContext context) { // Parse the URI Order order = ParseUriForOrderDetails(context.OutputStream)) { sw. } else { response = "Failure: Could not place order. } // Write to the response stream using (var sw = new StreamWriter(context.QueryString).Request.".

// Read the contents of the response OrderConfirmation orderConfirmation = null.ReadToEnd(). request. g()).ToString()).ToString()).Client‐Side URI Tunnelling public OrderConfirmation PlaceOrder(Order order) { // Create the URI var sb = new StringBuilder("http://restbucks.GetResponse().Size. StringBuilder("http://restbucks com/PlaceOrder?"). order.AppendFormat("&size={0}". } . order. order. // Create an OrderConfirmation object from the response orderConfirmation = new OrderConfirmation(str). sb.Create(").ToString()) as HttpWebRequest.Milk.Coffee. pp ( { } . sb. // Set up the GET request var request = HttpRequest.ToString()). sb.GetResponseStream())) { var str = sr.ToString()).AppendFormat("&consume-location={0}".ConsumeLocation.AppendFormat("coffee={0}". } return orderConfirmation. using (var sr = new StreamReader(response. // Get the response var response = request.Method = "GET". sb. order.AppendFormat("&milk={0}".

 RAILS. HttpListener.URI Tunnelling Strengths • Very easy to understand • Great for simple procedure‐calls • Simple to code – Do it with the servlet API. whatever! • Interoperable p – It’s just URIs! .  IHttpHandler.

URI Tunnelling Weaknesses • It’s brittle RPC! • Tight coupling. but against the Web for procedures  with side‐affects . map them to the function  manually • You typically use G GET T (prefer POST) – OK for functions. no metadata – No typing or “return values” specified in the URI • Not robust – have to handle failure cases  manually • No metadata support – Construct the URIs yourself.

POX Pattern
• Web servers understand how to process  requests with bodies
– Because they understand forms

• And how to respond with a body
– Because that’s ’  how the Web works

• POX uses HTTP POST to transfer XML  documents btw systems

Richardson Model Level 0
• Single well‐known  endpoint
– Not really URI friendly

• Doesn’t understand  HTTP
– Other than as a  transport

• No hypermedia

POX on the Wire
POST /Pl /PlaceOrder O d HTTP/1 1 HTTP/1.1 Content‐Type:  application/xml Host: Content‐Length:  361

client application  domain

<Order  xmlns=""> <CustomerId>abcd</CustomerId> <ConsumeAt>takeAway</ConsumeAt> <Items> <Item> <Name>latte</Name> <Quantity>1</Quantity> <Milk>whole</Milk> <Size>small</Size> </Item> <Item> <Name>cookie</Name>  <Kind>chocolate‐ chip</Kind> <Quantity>2</Quantity> </Item> </Items> </Order>

restbucks application  domain

HTTP/1.1  200  OK Content‐Length:  93 Content‐Type:  application/xml;  charset=utf‐8 Server:  Microsoft‐HTTPAPI/2.0 Date:  Mon,  04  Aug  2008  18:16:49  GMT <OrderConfirmation xmlns=""> <OrderId>1234</OrderId> </OrderConfirmation>

POX Architecture client li  application li i   domain d i savas 1 Local method call restbucks b k application li i   domain d i barista cashier Local method call jim ian 10 Local method  return waiter 6 Local method call  return 5 client‐side  dispatcher 2 XML document  into HTTP client XML document  from HTTP client 9 7 XML document  into HTTP response server‐side  dispatcher 4 XML document  from HTTP client  200 OK + XML  payload HTTP  client HTTP POST + XML  payload 8 HTTP  server 3 object dispatcher code communication .

Create(context.InputStream)).Request. XML document for  context... break.Xml.Write(returnValue. Dispatch it for processing request.XML_DECLARATION Turn the HTTP body into an+   result. and get bytes Return XML bytes to client .OuterXml).OutputStream.ToLower(). XmlElement result = MyApp.Length). q p string switch (verb) { case "post": Check HTTP Verb (we  { // Everything's Everything s done with post in this case want POST) XmlDocument request = new XmlDocument(). processing returnValue.. Get XML result.DocumentElement).ConvertUnicodeString(Constants.Response. } .Request.Trim().Load(XmlReader.Process(request. 0.Net POX Service Example F From  the h  Web W b server private void ProcessRequest(HttpListenerContext context) { g verb = context.HttpMethod. byte[] returnValue = Utils.

HttpServletResponse response) throws ServletException. String xmlRequest = extractPayload(requestReader).getWriter(). responseWriter = response. Order order = createOrder(xmlRequest). OrderConfirmation confirmation = restbucksService. embedPayload(requestWriter. request getReader().Java POX Servlet public class RestbucksService extends HttpServlet { @Override protected void doPost(HttpServletRequest request. confirmation.getReader(). } finally { // Cl Cleanup code d omitted itt d f for b brevity it } } .placeOrder(order). IOException { // Initialization code omitted for brevity try { requestReader = request.toString()).

ms = new MemoryStream(client. var responseXml = new XmlDocument().Save(ms). requestXml. responseXml.UploadData("http://restbucks. return CreateOrderConfirmation(responseXml). client. null.C# POX Client Example public OrderConfirmation PlaceOrder(string customerId. "application/xml"). var ms = new MemoryStream().Add("Content-Type".Headers. ms.ToArray())).com/PlaceOrder".Load(ms). items). Item[] items) { // Serialize our objects XmlDocument requestXml = CreateXmlRequest(customerId. } . var client = new WebClient().

"http://restbucks.0\"?>\n". // XML response handling omitted for brevity } private String sendRequestPost(String request. } } .". } finally { method.setRequestHeader( Content type". "UTF8"). private static final String NO_RESPONSE = "Error: No response. } return responseBody. method.getResponseBody(). Document xmlResponse l = DocumentBuilderFactory.. customerId String[] itemIds) throws Exception { // XML string creation omitted for brevity // .. public String placeOrder(String customerId.executeMethod(method).setRequestBody(XML_HEADING + request). String g responseBody p y = NO_RESPONSE.Java Apache Commons Client public class OrderingClient { private static final String XML XML_HEADING HEADING = "<?xml <?xml version=\"1.newInstance() . String response = sendRequestPost(request. HttpException { PostMethod method = new PostMethod(uri). "application/xml"). responseBody = new String(method. try { new HttpClient().newDocumentBuilder(). String uri) th throws IOException.parse( new InputSource(new StringReader(response))).com/PlaceOrder").releaseConnection(). method setRequestHeader("Contentmethod.

POX Strengths • Simplicity – just use HTTP POST and XML • Re‐use existing infrastructure and libraries • Interoperable – It’s just XML and HTTP • Can use complex data structures – By encoding 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  either .

CRUD Web Services: Embracing  HTTP as an Application Protocol .

 plus Caches.. . p plus.  servers. plus Uniform  Interface Fault model. p proxies. plus Status Codes Metadata. plus Runtime environment..Using the Web • URI tunnelling and POX use the Web as a  t transport t – Just like SOAP without metadata support • CRUD services begin to use the Web’s  coordination support HTTP • But the Web is more than transport – – – – – Headers Transport. etc Component model. . .

CRUD Resource Lifecycle • • • • The resource is created with POST It’s read with GET And updated via PUT Finally it’s removed using DELETE .

Richardson Model Level 2 • Lots of URIs • Understands HTTP! • No hypermedia .

Create with POST POST /orders <order … /> 201 Created Location: …/1234 /1234 Ordering  Client Ordering  Service 400 Bad Request 500 Internal Error .

POST Semantics • POST creates a new resource • But the server decides on that resource’s URI • Common human Web example: posting to  Web log – Server decides URI of posting and any comments  made on that post • Programmatic Web example: creating a new  employee record – And subsequently adding to it .

1 Host: restbucks. and HTTP  version . path.restbucks.restbucks+xml Content-Length: 225 Restbucks‐specific XML  <order xmlns="http://schemas.POST Request POST /orders HTTP/"> <location>takeAway</location> <items> <item> <name>latte</name> < <quantity>1</quantity> tit >1</ tit > <milk>whole</milk> Content <size>small</size> (again Restbucks XML) </item> </items> </order> content Content-Type:application/vnd.

POST Response HTTP/1.1 201 Created Location: /orders/1234 .

internalOrderId)).POST Implementation with a Servlet protected void doPost(HttpServletRequest request. String internalOrderId = OrderDatabase. } catch(Exception ex) { response.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR).getDatabase().setHeader("Location". response.SC_CREATED).saveOrder(order).setHeader( Location .setStatus(HttpServletResponse. response. } } . HttpServletResponse response) { t try { Order order = extractOrderFromRequest(request). computeLocationHeader(request. response.

Read with GET GET /orders/1234 200 OK <order … /> Ordering  Client Ordering  Service 404 Not Found 500 Internal I t l Error E .

GET Semantics • GET retrieves the representation of a resource • Should be idempotent – Shared understanding of GET semantics – Don’t violate that understanding! .

com .restbucks+xml Host: restbucks.GET Exemplified GET /orders/1234 HTTP/1.1 Accept: application/vnd.

com/order"> l "htt // h tb k / d " <location>takeAway</location> <items> <item> <name>latte</name> <quantity>1</quantity> <milk>whole</milk> milk whole /milk <size>small</size> </item> </items> <status>pending</pending> </order> .restbucks+xml Date: Wed.GET Response HTTP/1.1 200 OK Content-Length: 232 Content-Type: application/vnd. 19 Nov 2008 21:48:10 GMT <order d xmlns="http://schemas.restbucks.

When GET Goes wrong • Simple! – Just 404 – the resource is no longer available HTTP/1.1 /1 1 404 Not Found d Content-Type: application/vnd. 20 Dec 2008 19:01:33 GMT • Are you sure? – GET again! • GET is safe and idempotent – Great for crash recovery y scenarios! .restbucks+xml Content-Length: 952 Date: Sat.

g.Idempotent Behaviour • An action with no side affects – Comes from mathematics • In practice means two things: – A safe operation is one which changes no state at all • E. x = 4 rather than x += 2 • Web‐friendly y systems y  scale because of safety y – Caching! • And are fault tolerant because of idempotent  b h i behaviour – Just re‐try in failure cases .g. HTTP GET – An idempotent operation is one which updates state in an  absolute way • E.

} else { throw new WebApplicationException(404). } } // Remainder of implementation omitted for brevity } . } } catch (Exception e) { throw new WebApplicationException(500). if (order != null) { return xstream.toXML(order).GET JAX‐RS Implementation @Path("/") public class OrderingService { @GET @Produces("application/xml") @Path("/{orderId}") public String getOrder(@PathParam( getOrder(@PathParam("orderId") orderId ) String orderId) { try { Order order = OrderDatabase.getDatabase().getOrder(orderId).

Update with PUT PUT /orders/1234 <order … /> 200 OK Ordering  Client 404 Not Found Ordering  Service 409 Conflict 500 Internal Error .

PUT Semantics • PUT creates a new resource but the client  decides on the URI – Providing the server logic allows it • Also used to update existing resources by  overwriting iti  th them i in‐place l • PUT is idempotent p – Makes absolute changes • But is not safe – It changes state! .

1 1 Host: restbucks.PUT Request PUT /orders/1234 HTTP/1 HTTP/ Content-Type: application/xml Content-Length: 386 <order xmlns=""> <location>takeAway</location> <items> <item> <milk>whole</milk> <name>latte</name> <quantity>2</quantity> <size>small</size> </item> Updated content  <item> <milk>whole</milk> <name>cappuccino</name> <quantity>1</quantity> <size>large</size> </item> </items> <status>preparing</preparing> </order> .restbucks.

PUT Response HTTP/1. 30 Nov 2008 21:47:34 GMT g 0 Content-Length: Minimalist response contains no  entity body .1 200 OK Date: Sun. der"> <location>takeAway</location> <items> <item> <milk>whole</milk> <name>latte</name> / <quantity>2</quantity> <size>small</size> </item> <item> <milk>whole</milk> <name>cappuccino</name> <quantity>1</quantity> <size>large</size> g / </item> </items> <status>served</status> </order> • If we get errors  indicating incompatible  states (409.1 409 Conflict Date: Sun. 417) then  do some  forward/backward  compensating p g work – And maybe PUT again . 21 Dec 2008 16:43:07 GMT C t t L Content-Length:382 th 382 <order xmlns="http://schemas. or  some 4xx 4  errors simply i l   PUT again! – PUT i is id idempotent t t HTTP/1.When PUT goes wrong • If we get 5xx error.

Remove with DELETE DELETE /orders/1234 200 OK Ordering  Client 404 Not Found Ordering  Service 405 Method Not Allowed 500 Service Unavailable .

DELETE Semantics • Stop the resource from being accessible – Logical delete.1 200 OK Content Length: 0 Content-Length: Date: Tue. not necessarily physical • Request DELETE /orders/1234 HTTP/1. 16 Dec 2008 17:40:11 GMT .com • Response p HTTP/1.1 Host: restbucks.

 DELETE again! – Delete is idempotent! – DELETE once. 16 Dec 2008 17:42:12 GMT . DELETE 10 times has the same  effect: one deletion HTTP/1.1 404 Not Found Content-Length: 0 Date: Tue.When DELETE goes wrong • Simple case.

When DELETE goes Really Wrong • Some 4xx responses  i di indicate  that h  d deletion l i   isn’t possible – Th The state t t  of f the th  resource  isn’t compatible – Try forward/backward  compensation instead HTTP/1.restbucks.1 409 Conflict Content-Length: 379 D t Date: T Tue. 16 D Dec 2008 17:53:09 17 53 09 GMT <order xmlns=" der"> <location>takeAway</location> <items> <item> <name>latte</name> <milk>whole</milk> i / i <size>small</size> <quantity>2</quantity> </item> <item> <name>cappuccino</name> <milk>skim</milk> <size>large</size> <quantity>1</quantity> q y /q y </item> </items> <status>served</status> </order> Can’t delete an  order that’s  already served .

CRUD does not mean Worthless .

CRUD is Good? • CRUD is good – But it’s it s not great • CRUD‐style services use some HTTP features • But the application model is limited – Only suitable to CRUD Scenarios – Suits database‐style applications – Hence frameworks like Microsoft’s Astoria • CRUD has limitations – CRUD ignores hypermedia – CRUD encourages tight coupling through URI templates – CRUD encourages server and client to collude • The Web supports more sophisticated patterns than  CRUD! .

br • Discussion on the next class!! .Research Activity • Compare: p – REST Vs SOAP – REST Vs SOA – REST Vs WS‐* • Send a report to vaab@cin.ufpe.

Next class: Hypermedia and  RESTful RESTf l Services S i .

References • REST in Practice – Hypermedia and Systems Architecture Jim Webber. Savas Parastatidis. Savas‐ introduction . Ian Robinson Presentation for Universities.webber. shared by Jim Webber Somes slides adapted from a presentation for Universities (REST in  Practice ‐ A Tutorial l on Web b‐based b d Services) ) shared h d by b Jim Ji  W Webber bb    • • [http://jim. Ian Robinson Published by O’] • A Brief Introduction to REST http://www.infoq. 2010 REST in Practice ‐ A Tutorial on Web‐based Services Jim Webber.