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


 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 .Motivation • The web has radically transformed the way we produce and  share information – International ecosystem of application and sevices • We can search. combine. replicate. aggregate. transform.

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

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 .

 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. content delivery networks.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.etc • Together. 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. 7 .  proxies. caches.

8 .. Broken links. Why Why? ? • The Web as a platform is the result of its architectural  simplicity. ... p y. 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....Web As na Application Platform Platform. the use of a widely y implemented p  and agreed g ‐upon p   protocol (HTTP).

..Web As na Application Platform Platform. . XML and other formats are all just resources representation 9 .. *WS‐ Choreography..) really embraced the Web’s achitectural principals • Consistency and Uniformity – Principle of uniformity: HTML. 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..

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 .

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

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

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 .Key REST Principles • If you adhere to REST principles while designing your  application  you will end up with a system that exploits the  application.

.... • Resources are the fundamental building blocks of  web b‐based b d systems – A resource is anything we expose to the Web.. 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.

 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 • 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.

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

 MP3. they never access the underlying resource directly Human‐friendly machine‐friendly 17 . XML. plain text. or JPEG.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. comma‐separated values. such as XHTML. Atom. • 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.

xml or http://example.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 .xml or .org/order.json to indicate a preferred format 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 .

– Link Things to each other… 19 .  Instead  as the application reaches a new state.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. just like a state machine. Instead. state  the next possible  transitions are discovered.  – The difference from traditional state machines: the possible states  and the transitions between them are not known in advance.

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 .

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

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 .

... principles .Example: online shop • One p possibility: y  two Services Thinking g in REST  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 .

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

On The Wire .

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

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

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

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 .

 and get bytes Return XML bytes to client .ConvertUnicodeString(Constants. Dispatch it for processing request.HttpMethod. processing returnValue.Request. XmlElement result = MyApp.Xml.Request.Net POX Service Example F From  the h  Web W b server private void ProcessRequest(HttpListenerContext context) { g verb = context. 0.OutputStream.ToLower(). } .Response. Get XML result.Create(context.OuterXml).XML_DECLARATION Turn the HTTP body into an+   result..Write(returnValue. byte[] returnValue = Utils. XML document for  context.Process(request. 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(). break..InputStream))..Length).Trim().DocumentElement).Load(XmlReader.

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

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

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

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.. plus Uniform  Interface Fault model.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.  servers. . plus Runtime environment. p plus. . plus Status Codes Metadata.. . p proxies. 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 .

 and HTTP  version .com/order"> <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 Verb.restbucks.POST Request POST /orders HTTP/1.1 Host: Content-Type:application/vnd. path.restbucks+xml Content-Length: 225 Restbucks‐specific XML  <order xmlns="http://schemas.

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

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

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! .

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

19 Nov 2008 21:48:10 GMT <order d xmlns="http://schemas.restbucks.GET Response HTTP/1.restbucks+xml Date:"> 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> .1 200 OK Content-Length: 232 Content-Type: application/vnd.

When GET Goes wrong • Simple! – Just 404 – the resource is no longer available HTTP/1. 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.1 /1 1 404 Not Found d Content-Type: application/vnd.

 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 . HTTP GET – An idempotent operation is one which updates state in an  absolute way • E.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.g.

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.getOrder(orderId). } else { throw new WebApplicationException(404).getDatabase(). } } // Remainder of implementation omitted for brevity } . if (order != null) { return xstream. } } catch (Exception e) { throw new WebApplicationException(500).toXML(order).

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/"> <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> Content-Type: application/xml Content-Length: 386 <order xmlns="http://schemas.

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.

 or  some 4xx 4  errors simply i l   PUT again! – PUT i is id idempotent t t HTTP/1.1 409 Conflict Date: Sun. 417) then  do some  forward/backward  compensating p g work – And maybe PUT again .com/or 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. 21 Dec 2008 16:43:07 GMT C t t L Content-Length:382 th 382 <order xmlns="http://schemas.restbucks.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 .

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

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

com/or 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 .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.1 409 Conflict Content-Length: 379 D t Date: T Tue. 16 D Dec 2008 17:53:09 17 53 09 GMT <order xmlns="http://schemas.restbucks.

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! . • Discussion on the next class!! .Research Activity • Compare: p – REST Vs SOAP – REST Vs SOA – REST Vs WS‐* • Send a report to vaab@cin.

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

 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    • • [‐ introduction . Savas Parastatidis. Savas Parastatidis.References • REST in Practice – Hypermedia and Systems Architecture Jim] • A Brief Introduction to REST http://www.webber. Ian Robinson Presentation for Universities. 2010 REST in Practice ‐ A Tutorial on Web‐based Services Jim Webber. Ian Robinson Published by O’Reilly.