Some REST Design Patterns (and Anti-Patterns) - SOA Symposium 2009
- 1. Some REST Design Patterns (and Anti-Patterns) Cesare Pautasso Faculty of Informatics University of Lugano, Switzerland [email protected] http://www.pautasso.info
- 2. Abstract The REST architectural style is simple to define, but understanding how to apply it to design concrete REST services in support of SOA can be more complex. The goal of this talk is to present the main design elements of a RESTful architecture and introduce a pattern-based design methodology for REST services. A selection of REST-inspired SOA design patterns taken from the upcoming "SOA with REST" book will be explained and further discussed to share useful solutions to recurring design problems and to also the foundational building blocks that comprise the REST framework from a patterns perspective. We will conclude by introducing some common SOA anti-patterns particularly relevant to the design of REST services in order to point out that not all current Web services that claim to be RESTful are indeed truly so. ©2009 - Cesare Pautasso 2
- 3. Acknowledgements The following distinguished individuals have contributed to the the patterns and reviewed some of the material presented in this talk: Raj Balasubramanian Benjamin Carlyle Thomas Erl Stefan Tilkov Erik Wilde Herbjorn Wilhelmsen Jim Webber And all the participants, sheperds and sheeps of the SOA Patterns Workshop ©2009 - Cesare Pautasso 3
- 4. About Cesare Pautasso Assistant Professor at the Faculty of Informatics, University of Lugano, Switzerland (since Sept 2007) Research Projects: SOSOA – Self Organizing Service Oriented Architectures - CLAVOS – Continuous Lifelong Analysis and Verification of Open Services BPEL for REST Researcher at IBM Zurich Research Lab (2007) Post Doc at ETH Zürich - Software: JOpera: Process Support for more than Web services http://www.jopera.org/ Ph.D. at ETH Zürich, Switzerland (2004) Representations: http://www.pautasso.info/ (Web) http://twitter.com/pautasso/ (Twitter Feed) ©2009 - Cesare Pautasso 4
- 5. REST Patterns - Outline • Design Methodology • Simple Doodle Service Example & Demo • SOA Design Patterns • Entity Endpoint • Uniform Contract • Endpoint Redirection • Content Negotiation • Idempotent Capability • AntiPatterns • Tunneling everything through GET • Tunneling everything through POST ©2009 - Cesare Pautasso 5
- 6. Design Methodology for REST 1. Identify resources to be exposed as services (e.g., yearly risk report, book DELETE catalog, purchase order, open bugs, POST polls and votes) GET PUT 2. Model relationships (e.g., containment, reference, state transitions) between /loan resources with hyperlinks that can be followed to get more details (or perform /balance state transitions) /client 3. Define “nice” URIs to address the resources /book 4. Understand what it means to do a GET, POST, PUT, DELETE for each resource /order ? (and whether it is allowed or not) 5. Design and document resource representations /soap 6. Implement and deploy on Web server 7. Test with a Web browser ©2009 - Cesare Pautasso 6
- 7. Design Space M Representations (Variable) 4 Methods (Fixed) le) (Variab urces N Reso ©2009 - Cesare Pautasso 7
- 8. Simple Doodle API Example Design 1. Resources: DELETE polls and votes POST 2. Containment Relationship: GET PUT poll /poll {id1} /poll/{id} vote /poll/{id}/vote {id4} /poll/{id}/vote/{id} ? {id5} 3. URIs embed IDs of “child” instance resources 4. POST on the container is used to {id2} create child resources 5. PUT/DELETE for updating and {id3} removing child resources ©2009 - Cesare Pautasso 8
- 9. Simple Doodle API Example 1. Creating a poll (transfer the state of a new poll on the Doodle service) /poll /poll/090331x /poll/090331x/vote POST /poll GET /poll/090331x <options>A,B,C</options> 200 OK 201 Created <options>A,B,C</options> Location: /poll/090331x <votes href=“/vote”/> 2. Reading a poll (transfer the state of the poll from the Doodle service) ©2009 - Cesare Pautasso 9
- 10. Simple Doodle API Example Participating in a poll by creating a new vote sub resource - /poll /poll/090331x /poll/090331x/vote /poll/090331x/vote/1 POST /poll/090331x/vote GET /poll/090331x <name>C. Pautasso</name> <choice>B</choice> 200 OK <options>A,B,C</options> 201 Created <votes><vote id=“1”> Location: <name>C. Pautasso</name> /poll/090331x/vote/1 <choice>B</choice> </vote></votes> ©2009 - Cesare Pautasso 10
- 11. Simple Doodle API Example Existing votes can be updated (access control headers not shown) /poll /poll/090331x /poll/090331x/vote /poll/090331x/vote/1 PUT /poll/090331x/vote/1 GET /poll/090331x <name>C. Pautasso</name> <choice>C</choice> 200 OK <options>A,B,C</options> 200 OK <votes><vote id=“/1”> <name>C. Pautasso</name> <choice>C</choice> </vote></votes> ©2009 - Cesare Pautasso 11
- 12. Simple Doodle API Example Polls can be deleted once a decision has been made /poll /poll/090331x /poll/090331x/vote /poll/090331x/vote/1 DELETE /poll/090331x GET /poll/090331x 200 OK 404 Not Found ©2009 - Cesare Pautasso 12
- 13. Design Patterns M Representations (Variable) Content Negotiation 4 Methods (Fixed) le) (Variab Entity Uniform Endpoint Contract urces N Reso Endpoint Idempotent Redirect Capability ©2009 - Cesare Pautasso 13
- 14. Pattern: Uniform Contract calculateRate() Provider US retrieveTaxRate() Provider CH Consumer figureOutRateForTax() Provider IT How can consumers take advantage of multiple evolving service endpoints? Problem: Accessing similar services requires consumers to access capabilities expressed in service specific contracts. - The consumer needs to be kept up to date with respect to many evolving individual contracts. ©2009 - Cesare Pautasso 14
- 15. Pattern: Uniform Contract GET www.irs.gov/rate Provider US GET www.admin.ch/tax/rate Provider CH Consumer GET www.tesoro.it/tasse/iva Provider IT Solution: Standardize a uniform contract across alternative service endpoints that is abstracted from the specific capabilities of individual services. Benefits: Service Abstraction, Loose Coupling, Reusability, Discoverability, Composability. ©2009 - Cesare Pautasso 15
- 16. Example Uniform Contract CRUD REST Create a CREATE POST sub resource Retrieve the current READ GET state of the resource Initialize or update the UPDATE PUT state of a resource at the given URI Clear a resource, DELETE DELETE after the URI is no longer valid ©2009 - Cesare Pautasso 16
- 17. POST vs. GET GET is a read-only operation. It can be repeated without affecting the state of the resource (idempotent) and can be cached. Note: this does not mean that the same representation will be returned every time. Web browsers warn POST is a read-write you when refreshing operation and may change a page generated the state of the resource and with POST provoke side effects on the server. ©2009 - Cesare Pautasso 17
- 18. POST vs. PUT What is the right way of creating resources (initialize their state)? PUT /resource/{id} 201 Created Problem: How to ensure resource {id} is unique? (Resources can be created by multiple clients concurrently) Solution 1: let the client choose a unique id (e.g., GUID) POST /resource 301 Moved Permanently Location: /resource/{id} Solution 2: let the server compute the unique id Problem: Duplicate instances may be created if requests are repeated due to unreliable communication ©2009 - Cesare Pautasso 18
- 19. Pattern: Endpoint Redirection Stale Reference Consumer Service Endpoint Redirect Consumer Old Endpoint New Endpoint How can consumers of a service endpoint adapt when service inventories are restructured? Problem: Service inventories may change over time for business or technical reasons. It may not be possible to replace all references to old endpoints simultaneously. Solution: Automatically refer service consumers that access the stale endpoint identifier to the current identifier. ©2009 - Cesare Pautasso 19
- 20. Endpoint Redirection with HTTP /old /new HTTP natively supports the Endpoint redirection GET /old pattern using a combination of 3xx 301 Moved Permanently Location: /new status codes and standard headers: 301 Moved Permanently 307 Temporary Redirect GET /new Location: /newURI 200 OK Tip: Redirection responses can be chained. Warning: do not create redirection loops! ©2009 - Cesare Pautasso 20
- 21. Design Patterns M Representations (Variable) Content Negotiation 4 Methods (Fixed) le) (Variab Entity Uniform Endpoint Contract urces N Reso Endpoint Idempotent Redirect Capability ©2009 - Cesare Pautasso 21
- 22. Pattern: Entity Endpoint Provider Consumer Endpoint A B C X Y Z X Business Entities Z How can entities be positioned as reusable enterprise resources? Problem: A service with a single endpoint is too coarse-grained when its capabilities need to be invoked on its data entities. A consumer needs to work with two identifiers: a global one for the service and a local one for the entity managed by the service. Entity identifiers cannot be reused and shared among multiple services ©2009 - Cesare Pautasso 22
- 23. Pattern: Entity Endpoint Consumer Provider Entity Endpoints X Y Z A B C Solution: expose each entitity as individual lightweight endpoints of the service they reside in Benefits: Global addressability of service entities ©2009 - Cesare Pautasso 23
- 24. URI - Uniform Resource Identifier Internet Standard for resource naming and identification (originally from 1994, revised until 2005) Examples: http://tools.ietf.org/html/rfc3986 URI Scheme Authority Path https://www.google.ch/search?q=rest&start=10#1 Query Fragment REST does not advocate the use of “nice” URIs In most HTTP stacks URIs cannot have arbitrary length (4Kb) ©2009 - Cesare Pautasso 24
- 25. What is a “nice” URI? A RESTful service is much more than just a set of nice URIs http://map.search.ch/lugano http://maps.google.com/lugano http://maps.google.com/maps?f=q&hl=en&q=lugano, +switzerland&layer=&ie=UTF8&z=12&om=1&iwloc=addr ©2009 - Cesare Pautasso 25
- 26. URI Design Guidelines Prefer Nouns to Verbs GET /book?isbn=24&action=delete Keep your URIs short DELETE /book/24 If possible follow a “positional” parameter- Note: REST URIs are opaque passing scheme for identifiers that are meant to algorithmic resource query be discovered by following strings (instead of the hyperlinks and not key=value&p=v encoding) constructed by the client Some use URI postfixes to This may break the specify the content type abstraction Do not change URIs Warning: URI Templates Use redirection if you really introduce coupling between need to change them client and server ©2009 - Cesare Pautasso 26
- 27. Pattern: Content Negotiation Consumer ? Service New Consumer How can services support different consumers without changing their contract? Problem: Service consumers may change their requirements in a way that is not backwards compatible. A service may have to support both old and new consumers without having to introduce a specific capability for each kind of consumer. ©2009 - Cesare Pautasso 27
- 28. Pattern: Content Negotiation Consumer Service New Consumer Solution: specific content and data representation formats to be accepted or returned by a service capability is negotiated at runtime as part of its invocation. The service contract refers to multiple standardized “media types”. Benefits: Loose Coupling, Increased Interoperability, Increased Organizational Agility ©2009 - Cesare Pautasso 28
- 29. Content Negotiation in HTTP Negotiating the message format does not require to send more messages (the added flexibility comes for free) GET /resource Accept: text/html, application/xml, application/json 1. The client lists the set of understood formats (MIME types) 200 OK Content-Type: application/json 2. The server chooses the most appropriate one for the reply (status 406 if none can be found) ©2009 - Cesare Pautasso 29
- 30. Advanced Content Negotiation Quality factors allow the client to indicate the relative degree of preference for each representation (or media-range). Media/Type; q=X If a media type has a quality value q=0, then content with this parameter is not acceptable for the client. Accept: text/html, text/*; q=0.1 The client prefers to receive HTML (but any other text format will do with lower priority) Accept: application/xhtml+xml; q=0.9, text/html; q=0.5, text/plain; q=0.1 The client prefers to receive XHTML, or HTML if this is not available and will use Plain Text as a fall back ©2009 - Cesare Pautasso 30
- 31. Forced Content Negotiation The generic URI supports content negotiation GET /resource Accept: text/html, application/xml, application/json The specific URI points to a specific representation format using the postfix (extension) GET /resource.html GET /resource.xml GET /resource.json Warning: This is a conventional practice, not a standard. What happens if the resource cannot be represented in the requested format? ©2009 - Cesare Pautasso 31
- 32. Multi-Dimensional Negotiation Content Negotiation is very flexible and can be performed based on different dimensions (each with a specific pair of HTTP headers). Request Header Example Values Response Header Accept: application/xml, Content-Type: application/json Accept-Language: en, fr, de, es Content-Language: Accept-Charset: iso-8859-5, Charset parameter fo the unicode-1-1 Content-Type header Accept-Encoding: compress, Content-Encoding: gzip ©2009 - Cesare Pautasso 32
- 33. Pattern: Idempotent Capability Client Service Client Service Timeout Timeout !!! How can a service consumer recover from lost messages after network disruption or server failure within a service cluster? Problem: Service oriented architectures are distributed systems. Failures (such as the loss of messages) may occur during service capability invocation. A lost request should be retried, but a lost response may cause unintended side-effects if retried automatically. ©2009 - Cesare Pautasso 33
- 34. Pattern: Idempotent Capability Client ESB ESB Service Timeout Solution: use an ESB, with support for reliable messaging. Problem: do we always need this? Are there some messages more critical than others? ©2009 - Cesare Pautasso 34
- 35. Pattern: Idempotent Capability Client Service Simpler Solution: if possible use idempotent service capabilities, whereby services provide a guarantee that capability invocations are safe to repeat in the case of failures that could lead to a response message being lost ©2009 - Cesare Pautasso 35
- 36. Idempotent vs. Unsafe Idempotent requests can be Unsafe requests modify the state of processed multiple times the server and cannot be repeated without side-effects without additional (unwanted) effects: GET /book Withdraw(200$) //unsafe PUT /order/x Deposit(200$) //unsafe DELETE /order/y Unsafe requests require special If something goes wrong handling in case of exceptional (server down, server situations (e.g., state reconciliation) internal error), the request POST /order/x/payment can be simply replayed until In some cases the API can be the server is back up again redesigned to use idempotent Safe requests are operations: idempotent requests which B = GetBalance() //safe do not modify the state of B = B + 200$ //local the server (can be cached) SetBalance(B) //idempotent GET /book ©2009 - Cesare Pautasso 36
- 37. Dealing with Concurrency /balance Breaking down the API into a set of idempotent requests GET /balance helps to deal with temporary failures. 200 OK But what about if another ETag: 26 client concurrently modifies PUT /balance the state of the resource we ETag: 26 are about to update? Do we need to create an 200 OK explicit /balance/lock ETag: 27 resource? (Pessimistic Locking) Or is there an optimistic solution? ©2009 - Cesare Pautasso 37
- 38. Dealing with Concurrency /balance GET /balance 200 OK PUT /balance ETag: 26 ETag: 26 PUT /balance 200 OK ETag: 26 ETag: 27 409 Conflict The 409 status code can be used to inform a client that his request would render the state of the resource inconsistent ©2009 - Cesare Pautasso 38
- 39. Antipatterns - REST vs. HTTP REST HTTP “RPC” RESTful HTTP ©2009 - Cesare Pautasso 39
- 40. Antipatterns – HTTP as a tunnel Tunnel through one HTTP Method GET /api?method=addCustomer&name=Pautasso GET /api?method=deleteCustomer&id=42 GET /api?method=getCustomerName&id=42 GET /api?method=findCustomers&name=Pautasso* Everything through GET • Advantage: Easy to test from a Browser address bar (the “action” is represented in the resource URI) • Problem: GET should only be used for read-only (= idempotent and safe) requests. What happens if you bookmark one of those links? • Limitation: Requests can only send up to approx. 4KB of data (414 Request-URI Too Long) ©2009 - Cesare Pautasso 40
- 41. Antipatterns – HTTP as a tunnel Tunnel through one HTTP Method Everything through POST • Advantage: Can upload/download an arbitrary amount of data (this is what SOAP or XML-RPC do) • Problem: POST is not idempotent and is unsafe (cannot cache and should only be used for “dangerous” requests) POST /service/endpoint Is t h is a <soap:Envelope> reso <soap:Body> urce <findCustomers> ? <name>Pautasso*</name> </findCustomers> </soap:Body> </soap:Envelope> ©2009 - Cesare Pautasso 41
- 42. REST Design Patterns 1. Uniform Contract 2. Entity Endpoint 3. Entity Linking* 4. Content Negotiation 5. Distributed Response Caching* 6. Endpoint Redirection 7. Idempotent Capability 8. Message-based State Deferral* 9. Message-based Logic Deferral* 10.Consumer-Processed Composition* *Not Included in this talk ©2009 - Cesare Pautasso 42
- 43. References R. Fielding, Architectural Styles and the Design of Network- based Software Architectures, PhD Thesis, University of California, Irvine, 2000 C. Pautasso, O. Zimmermann, F. Leymann, RESTful Web Services vs. Big Web Services: Making the Right Architectural Decision, Proc. of the 17th International World Wide Web Conference (WWW2008), Bejing, China, April 2008 C. Pautasso, BPEL for REST, Proc. of the 7th International Conference on Business Process Management (BPM 2008), Milano, Italy, September 2008 C. Pautasso, Composing RESTful Services with JOpera, In: Proc. of the International Conference on Software Composition (SC2009), July 2009, Zurich, Switzerland. © 43
- 44. Conclusion Raj Balasubramanian, Applying the SOA composition principle to Benjamin Carlyle, Thomas Erl, REST gives interesting results Pautasso, Cesare Thanks to hyperlinks, REST SOA with a new brings REST, (more dynamic and loosely coupled) Prentice Hall, twist to SOA composition to appear in 2010 Composing RESTful services helps to build mashups, but is different A RESTful API is the perfect abstraction for publishing the state of a workflow ©2009 - Cesare Pautasso 44