REST Beyond the Intro Level

There is probably no developer left who hasn't been exposed to at least one introduction to REST, and most have by now gathered some first-hand experience. In this session, there will be no introduction, only advanced stuff, such as hypermedia aspects, security, format/resource/representation design, and implementation issues - with room for lots of questions (and hopefully, answers).

Transcript

1. © 2012 innoQ Deutschland GmbH REST Beyond the Intro Level Stefan Tilkov | @stilkov | WebTechCon 2012 Monday, October 15, 12
2. © 2006-2012 innoQ Deutschland GmbH 2 Stefan Tilkov stefan.tilkov@innoq.com @stilkov http://heise.de/developer/podcast/ innoQ Deutschland GmbH http://www.innoq.com Krischerstr. 100 40789 Monheim am Rhein Germany Phone: +49 2173 3366-0 innoQ Schweiz GmbH info@innoq.com Gewerbestr. 11 CH-6330 Cham Switzerland Phone: +41 41 743 0116 Monday, October 15, 12
3. http://rest-http.info Monday, October 15, 12
4. © 2012 innoQ Deutschland GmbH REST Intro Monday, October 15, 12
5. REpresentational State Transfer Monday, October 15, 12
6. The REST Uniform Interface identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages Monday, October 15, 12
7. The REST Uniform Interface 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 identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages Monday, October 15, 12
8. The REST Uniform Interface GET /customers/1234 Host: example.com Accept: application/vnd.mycompany.customer+xml <customer>...</customer> GET /customers/1234 Host: example.com Accept: text/x-vcard begin:vcard ... end:vcard identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages Monday, October 15, 12
9. The REST Uniform Interface <order self='http://example.com/orders/3321'> <item> <amount>23</amount> <product ref='http://example.com/products/4554' /> </item> <customer ref='http://example.com/customers/1234' /> <link rel='items' ref='http://example.com/orders/3321/items' /> </order> identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages Monday, October 15, 12
10. The REST Uniform Interface <order self='http://example.org/0E6C2BC1094C'> <item> <amount>23</amount> <product ref='http://amazon.com/A31138B3' /> </item> <customer ref='http://example.net/4E8F-891D' /> <link rel='items' ref='http://example.com/EFDBE4A38931' /> </order> identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages Stop Worrying About URI Design Monday, October 15, 12
11. The REST Uniform Interface identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages GET /service/customers/1234 HTTP 1.1 Host: www.example.com User-Agent: XYZ 1.1 Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Keep-Alive: 300 Connection: keep-alive If-Modified-Since: Fri, 02 Oct 2009 16:47:31 GMT If-None-Match: "600028c-59fb-474f6852c9dab" Cache-Control: max-age=60 HTTP/1.1 200 OK Date: Sun, 04 Oct 2009 19:36:25 GMT Server: Apache/2.2.11 (Debian) Last-Modified: Fri, 02 Oct 2009 16:47:31 GMT Etag: "600028c-59fb-474f6852c9dab" Cache-Control: max-age=300 Accept-Ranges: bytes Vary: Accept-Encoding Content-Encoding: gzip Content-Length: 7160 Keep-Alive: timeout=15, max=91 Connection: Keep-Alive Content-Type: application/xml <?xml version=‘1.0’ encoding=‘utf-8’ ?> ... Standard Method Media Type Data Control Data Visibility Monday, October 15, 12
12. getOrderDetails() updateQuote() cancelSubscription() findMatchingBid() initiateProcess() submitApplicationData() listAuctions() getUsers() Monday, October 15, 12
13. updateQuote() cancelSubscription() findMatchingBid() initiateProcess() submitApplicationData() listAuctions() getUsers() getOrderDetails() GET PUT POST DELETE Monday, October 15, 12
14. 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 Monday, October 15, 12
15. © 2012 innoQ Deutschland GmbH URIs ≠ APIs Monday, October 15, 12
16. © 2012 innoQ Deutschland GmbH http://example.org/ http://example.org/service/V1 http://example.org/service/V1/addresses;detailed http://example.org/service/V1/accounts http://example.org/service/V1/customers http://example.org/service/V1/customers/23/edit Monday, October 15, 12
17. © 2012 innoQ Deutschland GmbH http://example.org/ http://example.org/service/V1 http://example.org/service/V1/addresses;detailed http://example.org/service/V1/accounts http://example.org/service/V1/customers http://example.org/service/V1/customers/23/edit Fixed host “service” method/resource version ✗ Monday, October 15, 12
18. © 2012 innoQ Deutschland GmbH The only URIs you’ll ever need http://{my-entry-point} http://... Monday, October 15, 12
19. © 2012 innoQ Deutschland GmbH Service interfaces with hypermedia Monday, October 15, 12
20. © 2006-2012 innoQ Deutschland GmbH “Named” Links 20 Resource relationships in representations Independence from URI design Possible “De-Co-Location” Monday, October 15, 12
21. © 2006-2012 innoQ Deutschland GmbH 21 <link rel="edit" href="http://..."/> Client Server Monday, October 15, 12
22. © 2006-2012 innoQ Deutschland GmbH Service Documents 22 Document with links to “entry point” resources Can be consumer-speci c Additional “cheap” decoupling Federated if necessary Monday, October 15, 12
23. © 2011 innoQ Deutschland GmbH Service documents <services> <service id="lookup" href="http://..."/> <service id="crm" href="http://..."/> <service id="accounting" href="http://..."/> </services> Monday, October 15, 12
24. © 2006-2012 innoQ Deutschland GmbH Example 24 <?xml version="1.0" encoding="UTF-8"?> <serviceDescription xml:base="http://om.example.com"> <link rel="all" href="/orders/" /> <link rel="received" href="/orders/received/" /> <link rel="accepted" href="/orders/accepted/" /> <link rel="rejected" href="/orders/rejected/" /> <link rel="cancelled" href="/orders/cancelled/" /> <link rel="fulfilled" href="/orders/fulfilled/" /> <link rel="cancellations" href="/cancellations/" /> <link rel="reports" href="/reports/" /> </serviceDescription> <link rel="fulfilled" href="http://om.archive.com/orders/" / Monday, October 15, 12
25. © 2006-2012 innoQ Deutschland GmbH UDDI Publication n save_binding n save_business n save_service n save_tModel n delete_binding n delete_business n delete_publisherAssertions n delete_service n delete_tModel n add_publisherAssertions n set_publisherAssertions n get_assertionStatusReport n get_publisherAssertions n get_registeredInfo Inquiry n nd_binding n nd_business n nd_relatedBusinesses n nd_service n nd_tModel n get_bindingDetail n get_businessDetail n get_operationalInfo n get_serviceDetail n get_tModelDetail Dead as a parrot Monday, October 15, 12
26. © 2006-2012 innoQ Deutschland GmbH Link styles 26 <service id="lookup" href="http://..."/> <link rel="service" name="lookup" href="http://..."/> <link rel="lookup-service" href="http://..."/> Monday, October 15, 12
27. © 2012 innoQ Deutschland GmbH 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 Monday, October 15, 12
28. © 2012 innoQ Deutschland GmbH State Transition Links Determine the possible client actions Distinction from resource links is leaky since every link acts as state transition Monday, October 15, 12
29. © 2006-2012 innoQ Deutschland GmbH 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 29 <link rel="self" href="/orders/123" type="application/xml" <!-- ... --> /> Monday, October 15, 12
30. © 2006-2012 innoQ Deutschland GmbH Link Relations 30 <?xml version="1.0" encoding="UTF-8"?> <order xml:base="http://om.example.com"> <link rel="self" href="/orders/123" type="application/vnd.example.com-ordermgr+xml" / > <state>received</state> <link rel="payment" href="https://paypal/" /> <link rel="cancel" href="/cancellations/" /> <!-- ... --> </order> <?xml version="1.0" encoding="UTF-8"?> <orders xmlns="http://example.com/schemas/ordermanagement" xml:base="http://om.example.com"> <link rel="self" href="/orders/?page=3" /> <link rel="prev" href="/orders/?page=2" /> <link rel="next" href="/orders/?page=4" /> <!-- ... --> </orders> Monday, October 15, 12
31. © 2006-2012 innoQ Deutschland GmbH 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 31 HTTP/1.1 200 OK Link: <http://om.com/orders/?page=2>; rel="prev" Link: <http://om.com/orders/?page=4>; rel="next" Link: <http://xyz.com>; rel="prev" Link: <http://xyz.com>; rel="http://www.iana.org/ assignments/relation/prev" Monday, October 15, 12
32. © 2012 innoQ Deutschland GmbH JSON Home { "resources": { "http://example.org/rel/widgets": { "href": "/widgets/" }, "http://example.org/rel/widget": { "href-template": "/widgets/{widget_id}", "href-vars": { "widget_id": "http://example.org/param/widget" }, "hints": { "allow": ["GET", "PUT", "DELETE", "PATCH"], "representations": ["application/json"], "accept-patch": ["application/json-patch"], "accept-post": ["application/xml"], "accept-ranges": ["bytes"] } } } } http://tools.ietf.org/html/dra -nottingham-json-home-02 Monday, October 15, 12
33. © 2012 innoQ Deutschland GmbH Service interfaces vs. Hypermedia formats Monday, October 15, 12
34. © 2012 innoQ Deutschland GmbH System B Point-to-point integration Focus on single scenario Both systems known System A Monday, October 15, 12
35. © 2012 innoQ Deutschland GmbH Client 1 Service interfaces Server Single Server (Mostly) Expected scenarios Known and unknown clients Client 2 Client n … Monday, October 15, 12
36. © 2012 innoQ Deutschland GmbH Client 1 Hypermedia types Many servers – many clients Unexpected interactions Known and unknown clients & servers Client 2 Client n … Server A Server B Server n … Format Monday, October 15, 12
37. © 2012 innoQ Deutschland GmbH application/atom+xml Monday, October 15, 12
38. © 2012 innoQ Deutschland GmbH application/opensearchdescription+xml Monday, October 15, 12
39. © 2012 innoQ Deutschland GmbH text/html Monday, October 15, 12
40. © 2011 innoQ Deutschland GmbH Media type approach advantages Client & server independence Interoperability contract Re-use opportunities Library opportunity (without feeling weird) Monday, October 15, 12
41. © 2012 innoQ Deutschland GmbH “Loose coupling” only works if everyone’s in Monday, October 15, 12
42. © 2006-2012 innoQ Deutschland GmbH <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:element name="CatalogData"> <xsd:complexType > <xsd:sequence> <xsd:element name="books" type="bookdata" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:complexType name="bookdata"> <xsd:sequence> <xsd:element name="author" type="xsd:string"/> <xsd:element name="title" type="xsd:string"/> <xsd:element name="genre" type="xsd:string"/> <xsd:element name="price" type="xsd:float"/> <xsd:element name="publish_date" type="xsd:dateTime"/> <xsd:element name="description" type="xsd:string"/> </xsd:sequence> <xsd:attribute name="id" type="xsd:string"/> </xsd:complexType> </xsd:schema> // This file was generated by the JavaTM Architecture for XML // See <a href="http://java.sun.com/xml/jaxb">http://java.sun // Any modifications to this file will be lost upon recompila // 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 } Schemai cation Magic 42 Monday, October 15, 12
43. © 2006-2012 innoQ Deutschland GmbH Client rules Don’t depend on URI structure Support unknown links Ignore unknown content 43 Don’t break URI structure unnecessarily Evolve via additional resources Support older formats Server rules Monday, October 15, 12
44. © 2006-2012 innoQ Deutschland GmbH Postel’s law “TCP implementations should follow a general principle of robustness: Be conservative in what you do, be liberal in what you accept from others.” 44 http://tools.ietf.org/html/rfc761 Monday, October 15, 12
45. © 2012 innoQ Deutschland GmbH Be kind to each other Monday, October 15, 12
46. © 2012 innoQ Deutschland GmbH Postel’s Law Liberal, Loose, Tolerant Strict, Critical, Draconian Liberal, Loose, Tolerant Monday, October 15, 12
47. © 2012 innoQ Deutschland GmbH Versioning Monday, October 15, 12
48. © 2011 innoQ Deutschland GmbH REST Separation of Concerns Data Interaction Identity Monday, October 15, 12
49. © 2011 innoQ Deutschland GmbH Data media types content negotiation standard formats XML Schema & Co. Monday, October 15, 12
50. © 2011 innoQ Deutschland GmbH Interaction minimal set of methods standardized semantics uniformity general applicability Monday, October 15, 12
51. © 2011 innoQ Deutschland GmbH Identity Standardized IDs Self-contained Cross-application usage Long-lived Monday, October 15, 12
52. © 2012 innoQ Deutschland GmbH Major vs. Minor versions Monday, October 15, 12
53. © 2012 innoQ Deutschland GmbH Breaking vs. non-breaking Monday, October 15, 12
54. © 2012 innoQ Deutschland GmbH X 1.1 X 1.1 = Monday, October 15, 12
55. © 2012 innoQ Deutschland GmbH X 1.1 X 1.2 ≈ Monday, October 15, 12
56. © 2012 innoQ Deutschland GmbH X 1 X 1 = Monday, October 15, 12
57. © 2012 innoQ Deutschland GmbH X 1.1 X 2.0 ≠ Monday, October 15, 12
58. © 2012 innoQ Deutschland GmbH X Y ≠ Monday, October 15, 12
59. © 2011 innoQ Deutschland GmbH Versioning & media types Di erent major versions → di erent media type Compatible versions → same media type → Don’t use media types for versioning Monday, October 15, 12
60. © 2011 innoQ Deutschland GmbH Versioning strategy Keep URIs free of version numbers Add new resources for new aspects Reserve space for additional links Provide multiple representations Monday, October 15, 12
61. © 2012 innoQ Deutschland GmbH Documentation Monday, October 15, 12
62. © 2012 innoQ Deutschland GmbH Resources All The Way Down Order Shipment Fulfilment Customer Resource ProfileEntry SelfServiceUI Order Management Documentation Monday, October 15, 12
63. © 2011 innoQ Deutschland GmbH Documentation approaches External formal languages (WSDL, WADL) URI construction patterns Sample requests/responses Hyperlinked documentation Website = API Monday, October 15, 12
64. © 2011 innoQ Deutschland GmbH Security Monday, October 15, 12
65. © 2011 innoQ Deutschland GmbH Message-based vs. Transport- based Security Message-based encrypt/sign individual messages indefinite protection Slow, inefficient, scarcely used end-to-end persistent Transport-based ‣ encrypt communication channel ‣ protection while in transit ‣ fast, efficient, wide- spread ‣ not end-to-end ‣ not persistent SSL HTTPS REST WSS XML WS-* Monday, October 15, 12
66. © 2011 innoQ Deutschland GmbH HTTP Security Client accesses resource Server replies with 401 Unauthorized, including WWW-Authenticate: header Client re-issues request, including auth info (Authorization: header) Server either sends response or replies with 403 Forbidden Monday, October 15, 12
67. © 2011 innoQ Deutschland GmbH HTTP Basic Authentication Originally part of HTTP 1.0, now de ned in RFC 2617 Simple username/password exchange: →GET /calculations/4711 ←401 Unauthorized↵ WWW-Authentication: Basic realm=”zone1” →GET /calculations/4711↵ Authorization: Basic RtaW46c2VjcmV0Cg== ←200 OK base64enc(‘admin’ + ’:’ + ‘secret’): RtaW46c2VjcmV0Cg== Monday, October 15, 12
68. © 2011 innoQ Deutschland GmbH Basic Auth Problems Password basically sent in the clear (trivial encoding) Vulnerable to replay attacks Vulnerable to man-in-the-middle attacks No server identity guarantee Use Basic Auth with SSL only Monday, October 15, 12
69. © 2011 innoQ Deutschland GmbH HTTP Digest Auth Idea: sent password digest instead of password Combine with server-generated nonce to prevent replays Digest: One-way information checksum generation algorithm examples: MD5, SHA Monday, October 15, 12
70. © 2011 innoQ Deutschland GmbH HTTP Digest Authentication Protected authorization info exchange: →GET /calculations/4711 ←401 Unauthorized↵ WWW-Authentication: Digest realm=”zone1” nonce=”63ADC...” →GET /calculations/4711↵ Authorization: Digest ... md5(nonce+password) ←200 OK Monday, October 15, 12
71. © 2011 innoQ Deutschland GmbH HTTP Digest Evaluation Prevents replays Prevents password sni ng Not widely used Protects security info only, not data Monday, October 15, 12
72. © 2011 innoQ Deutschland GmbH Other mechanisms SPNEGO (http://tools.ietf.org/html/rfc4178) Kerberos (via Apache Module) Windows Server Authentication Monday, October 15, 12
73. © 2011 innoQ Deutschland GmbH Externalized Auth Setup WebServer Client HTTPS HTTPS User Store/ Identity Mgmt Application HTTP + User + PW + User + PW + User + User + PW Auth yes/no <Location "/orders"> SSLRequireSSL AuthName "OrderManagement" AuthType Basic AuthUserFile /etc/apache2/users AuthGroupFile /etc/apache2/groups Require group internal </Location> <Location "/orders"> SSLRequireSSL AuthName "OrderManagement" AuthType Basic AuthLDAPurl ldap://localhost:389/ou=users,dc=domain,dc=country?uid Require valid-user </Location> Monday, October 15, 12
74. © 2011 innoQ Deutschland GmbH Cookie-based Authentication Overall problems with HTTP Auth: no logout in browser no custom login screen Cookie-based authentication: Use HTML form to submit username/password Return user-speci c cookie Browser sends cookie with each request Monday, October 15, 12
75. © 2011 innoQ Deutschland GmbH Cookies RESTful? Cookies commonly considered REST anti- pattern But: Cookies can be RESTful RESTful HTTP doesn’t match session state Cookie usage without sessions is perfectly ne Monday, October 15, 12
76. © 2011 innoQ Deutschland GmbH Cookie Recipe Ingredients: 1 server-side secret user name/password validation on server (LDAP, DB, ...) Approach: ask user for name and password if no cookie passed authenticate user create auth token as username + expiry date hash(auth token + server secret) return cookie as hash + auth_token server validates with algorithm on in-memory data Monday, October 15, 12
77. © 2011 innoQ Deutschland GmbH OpenID HTTP-based, simple, distributed, multi-party single-sign on mechanism Uses URIs as user ids Originally created for blog comments Monday, October 15, 12
78. © 2011 innoQ Deutschland GmbH OpenID Approach Server prompts client to authenticate Client sends OpenID (URI) Server GETs URI (X)HTML contains link(s) to identity provider Server and ID provider establish shared secret Server redirects client to ID provider (some login) redirect back Monday, October 15, 12
79. © 2011 innoQ Deutschland GmbH OpenID 1. User is presented with OpenID login form by the Consumer 2. User responds with the URL that represents their OpenID 3. Consumer canonicalizes the OpenID URL and uses the canonical version to request (GET) a document from the Identity Server. 4. Identity Server returns the HTML document named by the OpenID URL 5. Consumer inspects the HTML document header for <link/> tags with the attribute rel set to openid.server and, optionally, openid.delegate. The Consumer uses the values in these tags to construct a URL with mode checkid_setup for the Identity Server and redirects the User Agent. This checkid_setup URL encodes, among other things, a URL to return to in case of success and one to return to in the case of failure or cancellation of the request 6. The OpenID Server returns a login screen. 7. User sends (POST) a login ID and password to OpenID Server. 8. OpenID Server returns a trust form asking the User if they want to trust Consumer (identified by URL) with their Identity 9. User POSTs response to OpenID Server. 10. User is redirected to either the success URL or the failure URL returned in (5) depending on the User response 11. Consumer returns appropriate page to User depending on the action encoded in the URL in (10) Source: Phil Windley, http://www.windley.com/archives/2006/04/how_does_openid.shtml unnecessary if logged in to IdP unnecessary if logged in to destination Monday, October 15, 12
80. © 2011 innoQ Deutschland GmbH Authorization As a user, I want to … allow del.icio.us to post to my blog once a day allow a service to archive my Flickr photos enable an address importer to access my XING or LinkedIn data So, let’s give them my user id and password! No, not really. Monday, October 15, 12
81. © 2011 innoQ Deutschland GmbH OAuth 1. Consumer redirects end user’s browser to Service Provider’s web site, including redirect URI 2. Service Provider authenticates user and asks for acceptance, redirects end user’s browser to Consumer with authorization grant 3. Consumer exchanges auth grant for auth token 4. Consumer can access Service provider’s protected resource using auth token Monday, October 15, 12
82. © 2012 innoQ Deutschland GmbH Backend 1 Backend 2 Auth-Provider Browser Login Credentials Ticket Validation Request + Ticket Request + Ticket Algorithmic Validation Monday, October 15, 12
83. © 2012 innoQ Deutschland GmbH Cookie/OAuth Token Integration Frontend Server Browser Cookie Backend Server Backend Server Token Token Monday, October 15, 12
84. © 2012 innoQ Deutschland GmbH Q&A Stefan Tilkov stefan.tilkov@innoq.com http://www.innoq.com/blog/st/ @stilkov Phone: +49 170 471 2625 innoQ Deutschland GmbH http://www.innoq.com Krischerstr. 100 40789 Monheim am Rhein Germany Phone: +49 2173 3366-0 innoQ Schweiz GmbH info@innoq.com Gewerbestr. 11 CH-6330 Cham Switzerland Phone: +41 41 743 0116 Monday, October 15, 12