Session 6 Patterns and best practices in SOA/REST

Session 6 Patterns and best practices in SOA/REST Sistemas Distribuidos Diego Sevilla Ruiz DITEC Facultad de Informática Murcia, 2012 Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 1 / 34

Contents 1 Introduction 2 SOA & REST Patterns Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 2 / 34

Introduction We will see advanced uses of REST Will be compared with more traditional approaches This architecture can scale much more than traditional ones Farewell to relational DB and the normal forms :) Use of caches and functional programming is essential Study: Memcached and MapReduce Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 4 / 34

Summary of REST Everything is a resource (either representing a set or an element) Resources are identified by URIs Use of HTTP verbs (CRUD) to obtain and modify resources Importance of MIME types (microformats) State is passed in the client/server communication HATEOAS: Hypermedia as the Engine of Application State 1 1 http: //roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven, http://en.wikipedia.org/wiki/hateoas. Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 5 / 34

SOA & REST Patterns Based on the talk by Cesare Pautasso 2 The idea: REST concepts are relatively simple However, implementing well-behaved REST based services is not easy We ll see patterns and anti-patterns 2 REST-Inspired SOA Design Patterns (and Anti-Patterns), http://www.infoq.com/presentations/some-rest-design-patterns. Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 7 / 34

REST Design Methodology 1 Identify the resources that are exposed as services 2 Model relationships (containment, reference) between resources with bindings (Note how this is similar to the metamodel seen, Ecore) 3 Define resource-friendly URLs (not strictly needed, but helps) 4 Understand what means to GET, POST, PUT, and DELETE, for each resource (and whether it is allowed or not) 5 Design and document resource representations (JSON, XML, microformats, etc.) 6 Implement deployment it on a web server 7 Try with a browser Working elements Resources and Representations Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 8 / 34

Example: Doodle Service Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 9 / 34

Usage: Create a poll POST to create the poll: POST /poll <options>a, B, C</options> 201 Created Location: /poll/432432 Obtain the poll: GET /poll/432432 200 OK <options>a, B, C</options> <votes href="/vote"/> XML is used in this case The resource is appended by the internal resource In other representations the link will be specified differently iego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 10 / 34

Usage: Voting POST to create a vote: POST /poll/432432/vote <name>diego Sevilla</name> <choice>c</choice> 201 Created Location: /poll/432432/vote/1 Obtain the poll: GET /poll/432432 200 OK <options>a, B, C</options> <votes><vote id="1"> <name>...</name> <choice>c</choice> </vote></votes> You get all the votes (the link could have been used instead) Implementation decision (regarding content... size?) iego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 11 / 34

Patterns Summary Uniform Contract Use of fixed methods Entity Endpoint How are they named? Entity Linking Relationship between entities discovered through linking Entity Redirection Redirection allows load balancing, fault tolerance, etc. Content Negotiation Allows multiple clients, evolution Idempotent Capability As in the web, you should pursue this quality (functional style) Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 12 / 34

Pattern - Uniform Contract Building APIs tightly couples clients and servers Hinders application evolution A customer needs to know multiple APIs of different service providers Solution: Provide a uniform interface (eg. HTTP verbs) that hides the specifics of each service Advantages: Service Abstraction, loose coupling, reusability, composition of services, etc. Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 13 / 34

Pattern - Uniform Contract (ii) POST vs. GET vs. PUT GET is a read-only operation POST modifies server state (hence browsers ask if we want to forward the request) How to create resources? PUT /recurso/<id> What if it s repeated? GUID provided by the client? POST /recurso 301 Moved Permanently/201 Created Location: /recurso/<id> Problem: it is not idempotent (duplication in case of failure in communications) Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 14 / 34

Pattern - Addressing resources The service acts as a façade of the resources Increases service granularity (less reusable) Clients are tied to that API It is hardcoded in the client code API evolution (new services, resources)? Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 15 / 34

Pattern Addressing resources (ii) Offer all reusable resources through services Linking allows them to be reused in other sites Fine-grained resource access increases reusability Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 16 / 34

Pattern Addressing resources (iii) URI design Prefer noun to verbs GET /resource/id=89?action=delete Short URLs DELETE /resource/66 Prefer URLs with positional parameters instead of key/value pairs Do not use postfixes with the type (eg..xml,.json) Break content negotiation (will see later) URLs should not change Use redirection if needed Beware: URIs patterns create dependency between client and server (they are like APIs) Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 17 / 34

Entity Linking Problem: Business entities have natural relationships, yet entity services are commonly designed autonomously with no indication of these relationships Service consumers acting as composition controllers are commonly required to have entity linking logic hard-coded in order to work with entity relationships Governance burden to ensure that hard-coded entity linking logic is kept in synch with the business Solution: Services inform their consumers about the existence of related entities as part of the consumer s interactions with the services Links are included in relevant response messages from the service. Service consumers are able to navigate from entity to entity by following these links, and accumulate further business knowledge along the way Decouples a priori client knowledge of the internal business logic Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 18 / 34

Entity Linking (ii) Services that expose identifiers of related entities to service consumers are able to be used in a wider variety of compositions. E. g. the Invoice Printer service is able to then cross-reference invoice and customer records in order to print mailing labels. Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 19 / 34

Entity Linking (iii) Doodle example: /poll/432432: 200 OK <options>a, B, C</options> <votes href=/vote/> /poll/43243/vote/1: <vote><id>1</id><name>name</name><choice>c</choice></vote> /poll/43243/vote/2: <vote><id>2</id><name>other</name><choice>b</choice></vote> Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 20 / 34

Pattern - Redirection of resources HTTP natively supports redirection with 3xx: GET /old/x 301 Moved Permanently Location: /new/y GET /new/y 200 OK You can also return the 307 code (Temporary Redirect) It can be used for load balancing Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 21 / 34

Pattern Content Negotiation How to support different clients? Versions Capabilities Expectations (requirements) In an evolutive way? Solution: Specify the version and features based on media types Microformats (curious that the author does not mention them) Advantages: Loose Coupling, greater interoperability, etc. Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 22 / 34

Pattern Content Negotiation (ii) It does not require the use of more messages: GET /resource Accept: text/html, application/json 200 OK Content-type: application/json (Response 406 if required content-type cannot be served) Specifiers can be used to specify preferences as: Accept: text/html;q=0.1, application/json;q=0.9 Also in different dimensions: Accept-Language, Accept-Encoding, Accept-Charset, etc. Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 23 / 34

Pattern Idempotent Capability How to protect from message failures in distributed systems? Missing one message means sending the message twice Solution Use ESB/MOM (provides messages with failover) Design requests to be idempotent (REST philosophy) Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 24 / 34

Pattern Idempotent Capability (ii) Idempotent vs. Not secure Idempotent requests can be sent several times without problems: GET /book/x PUT /poll/y DELETE /libro/z If anything fails, the request can be retried Secure answers are those not modifying server state (GET) Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 25 / 34

Pattern Idempotent Capability (iii) Idempotent vs. Not secure Requests that modify the state are non-secure : withdraw(account1, 200) deposit(account2, 200) POST /clients If anything fails in the latter case, additional mechanisms will be required for reconciliation of state (using identifiers, etc.) Sometimes APIs can be designed so that they are idempotent: B = getbalance(); // Idempotent B = B + 200; // Local setbalance(b); // Idempotent Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 26 / 34

Pattern Idempotent Capability (iv) Concurrency What if another client accesses in the meantime? Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 27 / 34

Pattern Idempotent Capability (v) Optimistic Concurrency Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 28 / 34

Anti-patterns Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 29 / 34

Richardson REST Maturity Model http: //martinfowler.com/articles/richardsonmaturitymodel.html Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 30 / 34

Richardson REST Maturity Model (ii) 0 HTTP as an RPC Protocol (Tunnel POST+POX or POST+JSON) 1 Multiple Resource URIs (Fine-Grained Global Addressability) 2 Uniform HTTP Verbs (Contract Standardization) 3 Hypermedia (Protocol Discoverability) Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 31 / 34

Anti-patterns HTTP as tunnelling GET /api?method=addcustomer&name=diego GET /api?method=deletecustomer&id=42 Everything using GET Advantage: You can use it easily from a browser Drawbacks: GET should be used for idempotent requests (caching, fault tolerance, etc.) Some systems have limitations on the size of the URL Everything using POST Advantage: You can send any data size (used by SOAP) Drawbacks: POST is not idempotent so cannot be cached POST /service/endpoint Is /service/endpoint a resource? Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 32 / 34

References C. Pautasso Some REST Design Patterns (and Anti-Patterns) http://www.jopera.org/docs/talks/2009/rest-patterns InfoQ (varios autores) InfoQ Explores REST http://www.infoq.com/resource/minibooks/ emag-03-2010-rest/en/pdf/rest%20emag.pdf S. Tilkov REST Anti-Patterns y REST doubts http://www.infoq.com/articles/rest-anti-patterns http://www.infoq.com/articles/tilkov-rest-doubts M. Paternostro, K. Hussey Building RESTful Java Applications with EMF http://www.slideshare.net/kenn.hussey/ building-restful-java-applications-with-emf Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 33 / 34

References (ii) L. Richardson, S. Ruby RESTful Web Services O Reilly, 2007, ISBN: 0-596-52926-0 R. Balasubramanian, B. Carlyle, T. Erl, C. Pautasso SOA with REST: Principles, Patterns & Constraints Prentice Hall, Pearson, 2012, ISBN: 0-137-01251-0 http://soabooks.com/rest/ Diego Sevilla Ruiz (DITEC Facultad de Informática) Session 6 Patterns and best practices in SOA/REST Murcia, 2012 34 / 34