REST Beyond the Intro Level

Slide 1

Slide 1 text

Slide 2

Slide 2 text

© 2006-2012 innoQ Deutschland GmbH 2 Stefan Tilkov [email protected] @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 [email protected] Gewerbestr. 11 CH-6330 Cham Switzerland Phone: +41 41 743 0116 Monday, October 15, 12

Slide 3

Slide 3 text

http://rest-http.info Monday, October 15, 12

Slide 4

Slide 4 text

Slide 5

Slide 5 text

REpresentational State Transfer Monday, October 15, 12

Slide 6

Slide 6 text

The REST Uniform Interface identiﬁcation of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages Monday, October 15, 12

Slide 7

Slide 7 text

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 identiﬁcation of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages identiﬁcation of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages Monday, October 15, 12

Slide 8

Slide 8 text

The REST Uniform Interface GET /customers/1234 Host: example.com Accept: application/vnd.mycompany.customer+xml ... GET /customers/1234 Host: example.com Accept: text/x-vcard begin:vcard ... end:vcard identiﬁcation of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages Monday, October 15, 12

Slide 9

Slide 9 text

The REST Uniform Interface 23 identiﬁcation of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages Monday, October 15, 12

Slide 10

Slide 10 text

The REST Uniform Interface 23 identiﬁcation 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

Slide 11

Slide 11 text

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 ... Standard Method Media Type Data Control Data Visibility Monday, October 15, 12

Slide 12

Slide 12 text

getOrderDetails() updateQuote() cancelSubscription() ﬁndMatchingBid() initiateProcess() submitApplicationData() listAuctions() getUsers() Monday, October 15, 12

Slide 13

Slide 13 text

updateQuote() cancelSubscription() ﬁndMatchingBid() initiateProcess() submitApplicationData() listAuctions() getUsers() getOrderDetails() GET PUT POST DELETE Monday, October 15, 12

Slide 14

Slide 14 text

interface Resource { Resource(URI u) Response get() Response post(Request r) Response put(Request r) Response delete() } generic speciﬁc 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

Slide 15

Slide 15 text

Slide 16

Slide 16 text

© 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

Slide 17

Slide 17 text

Slide 18

Slide 18 text

Slide 19

Slide 19 text

Slide 20

Slide 20 text

Slide 21

Slide 21 text

Slide 22

Slide 22 text

© 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

Slide 23

Slide 23 text

Slide 24

Slide 24 text

Slide 25

Slide 25 text

© 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

Slide 26

Slide 26 text

Slide 27

Slide 27 text

© 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

Slide 28

Slide 28 text

Slide 29

Slide 29 text

© 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 /> Monday, October 15, 12

Slide 30

Slide 30 text

Slide 31

Slide 31 text

© 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: ; rel="prev" Link: ; rel="next" Link: ; rel="prev" Link: ; rel="http://www.iana.org/ assignments/relation/prev" Monday, October 15, 12

Slide 32

Slide 32 text

© 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

Slide 33

Slide 33 text

Slide 34

Slide 34 text

Slide 35

Slide 35 text

Slide 36

Slide 36 text

© 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

Slide 37

Slide 37 text

Slide 38

Slide 38 text

Slide 39

Slide 39 text

Slide 40

Slide 40 text

© 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

Slide 41

Slide 41 text

Slide 42

Slide 42 text

© 2006-2012 innoQ Deutschland GmbH // This file was generated by the JavaTM Architecture for XML // See 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

Slide 43

Slide 43 text

© 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

Slide 44

Slide 44 text

© 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

Slide 45

Slide 45 text

Slide 46

Slide 46 text

Slide 47

Slide 47 text

Slide 48

Slide 48 text

Slide 49

Slide 49 text

Slide 50

Slide 50 text

Slide 51

Slide 51 text

Slide 52

Slide 52 text

Slide 53

Slide 53 text

Slide 54

Slide 54 text

Slide 55

Slide 55 text

Slide 56

Slide 56 text

Slide 57

Slide 57 text

Slide 58

Slide 58 text

Slide 59

Slide 59 text

Slide 60

Slide 60 text

© 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

Slide 61

Slide 61 text

Slide 62

Slide 62 text

Slide 63

Slide 63 text

© 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

Slide 64

Slide 64 text

Slide 65

Slide 65 text

© 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

Slide 66

Slide 66 text

© 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

Slide 67

Slide 67 text

© 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

Slide 68

Slide 68 text

© 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

Slide 69

Slide 69 text

© 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

Slide 70

Slide 70 text

© 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

Slide 71

Slide 71 text

Slide 72

Slide 72 text

Slide 73

Slide 73 text

© 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 SSLRequireSSL AuthName "OrderManagement" AuthType Basic AuthUserFile /etc/apache2/users AuthGroupFile /etc/apache2/groups Require group internal SSLRequireSSL AuthName "OrderManagement" AuthType Basic AuthLDAPurl ldap://localhost:389/ou=users,dc=domain,dc=country?uid Require valid-user Monday, October 15, 12

Slide 74

Slide 74 text

© 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

Slide 75

Slide 75 text

© 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

Slide 76

Slide 76 text

© 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

Slide 77

Slide 77 text

Slide 78

Slide 78 text

© 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

Slide 79

Slide 79 text

© 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 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

Slide 80

Slide 80 text

© 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

Slide 81

Slide 81 text

© 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

Slide 82

Slide 82 text

Slide 83

Slide 83 text

Slide 84

Slide 84 text

© 2012 innoQ Deutschland GmbH Q&A Stefan Tilkov [email protected] 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 [email protected] Gewerbestr. 11 CH-6330 Cham Switzerland Phone: +41 41 743 0116 Monday, October 15, 12