1. All Contents © 2007 Burton Group. All rights reserved. Code Talks: Demonstrating the "ilities" of REST Peter Lacey Senior Consultant placey@burtongroup.com placey@wanderingbarque.com www.burtongroup.com wanderingbarque.com/nonintersecting Thursday – November 8 th, 2007

2. Demonstrating the ilities of REST Who am I? I am not an analyst! I am a consultant in Burton Groups Application Platform Strategies service Ive been known to blog Use to work for Systinet (now HP), Cisco, Netscape (now defunct), and others REST proponent

3. Demonstrating the ilities of REST What is REST? REST defines a series of constraints for distributed systems that together achieve the properties of: A system that exhibits all defined constraints is RESTful Systems may add additional constraints or relax existing constraints, in which case they are more or less RESTful Constraints have trade offs Simplicity Scalability Modifiability Performance Visibility (to intermediaries) Portability Reliability

4. Demonstrating the ilities of REST ConstraintPropertyTrade Off Client-ServerSimplicity, scalability, modifiability StatelessScalability, simplicity, reliability, visibility, modifiabilityDegrades efficiency CacheableScalability, performanceDegrades reliability Uniform InterfaceSimplicity, visibility, modifiabilityDegrades efficiency Layered SystemScalability, security, legacy integration, modifiabilityAdds latency Identification of ResourcesRequired by uniform interface. Simplicity, scalability, modifiability Manipulation via representations Required by uniform interface and stateless. Simplicity, visibility, performance, modifiability Increases bandwidth Self-descriptive messagesRequired by stateless, cachebale, uniform interface, and layered system. Visibility, performance, modifiability Hypermedia as the engine of application state Required by uniform interface. Scalability, reliability, performance, modifiability Code on demand (optional)ModifiabilityReduces visibility Summary of REST constraints

5. Demonstrating the ilities of REST What Ill be talking about today Accessibility: A new -ility The sum of: simplicity, scalability / 2, and modifiability / 2 The ability for people to get to the information they want, when they want it The ability to manipulate that information as needed

6. Demonstrating the ilities of REST What Ill be talking about today (continued) Modifiability: Extensibility : The ability to add new functionality to a deployed system Evolvability : The ability to change existing functionality dynamically Configurability : The ability to influence a deployed applications functionality (that is, make clients use or become aware of newly deployed functionality) Reusability : The ability for deployed resources to be reused by multiple applications Customizability : The ability to temporarily specialize component behavior

7. Demonstrating the ilities of REST Rule # 1: The identification of resources constraint Everything of value is URI addressable /users/placey/expenses /users/placey/expenses/123/ /users/placey/expenses/123/line_items /users/placey/expenses/123/line_items/2 /expenses;pending /2006/expenses /2006/expenses/total /expenses;pending?start=10 /expenses[total gte 1000] (Astoria syntax)

8. Demonstrating the ilities of REST Rule # 2 See rule # 1 URIs have interesting properties Support for following and manipulating URIs is enabled in many applications and all programming languages URIs can be: linked to, written down, memorized, emailed, IMd, bookmarked URIs enable both versions of the Web You can tag them, vote on them, pipe them into other apps Information is now accessible to one degree or another to anyone: managers, shadow IT, proto-geeks, mom

9. Demonstrating the ilities of REST Rule # 2 (continued) Allows for system to be extended simply by adding new resources But keep those URIs cool. Cool URIs dont change If they have to, use redirects (e.g. 301) Use descriptive URIs for human accessibility Client developers should treat URIs as opaque That is, code should not assemble URIs based on a perceived pattern. The pattern might change. Does not conflict with descriptive URIs, those are for humans This is not always possible, in which case resource developers should publish the recipe

10. Demonstrating the ilities of REST Rule # 3 There is, of course, no rule # 3

11. Demonstrating the ilities of REST Rule # 4: The self-descriptive messages constraint Use media types (aka MIME types, message formats) that are broadly understood The more existing clients that can participate the better Strongly consider XHTML Consider multiple representations of a single resource XML (with agreed upon, if not IANA sanctioned, content type, e.g. application/expense+xml) JSON, for when your really pushing data structures around Atom feeds for event data PDFs, images, audio, if desired (no MTOM, SwA, DIME required) Consider unique resources for each representation

12. Rule # 4 (continued) Learn and use the HTTP headers A message is more than the entity body Accept: [media type], Accept-Language, Accept-Encoding, Accept- Charset Content-Type: [media type] Location: [URL], Content-Location [URL] Last-Modified [date], If-Modified-Since [Date], If-Unmodified-Since [Date] ETag [UID] / If-None-Match [UID] / If-Match [UID] Expires / Cache-Control [argument]

13. Demonstrating the ilities of REST Rule # 4 (continued) XHTML? Really? It's XML, so it's parseable, XPathable, XQueryable, XCeterable It's more accessible Information available to anyone with a browser (IE issues aside) Or an RSS reader or anything else that understands HTML Has useful constructs for links, lists, name/value pairs, etc. Graceful degradation from dedicated client to generic client The class, rel, etc. attributes provide the necessary semantic value No practical difference between: 1000.00 And 1000.00 Consider returning stylesheets and nicely formatted pages too; honored by browsers, ignored otherwise

14. Demonstrating the ilities of REST A diversion on microformats Extends XHTML to give semantic meaning to HTML tags Extensions done with certain attributes: e.g. class, rel, rev Formal microformats exist: http://microformats.org/http://microformats.org/ geo: latitude and longitude hCard: contact information A dozen more Often contrasted with the Semantic Web: RDF/OWL Simpler Leverages existing content Strongly encouraged to use XHTML representations with official or custom microformats GEO: latitude: 37.386013, longitude: -122.082932

15. Demonstrating the ilities of REST Rule # 5: The uniform interface constraint Obey the semantics of the HTTP interface GET and HEAD retrieve resource representations and metadata Safe and idempotent If GET breaks something, its your (the resource owners) fault. PUT Updates resources Creates resources at the client chosen URL (if allowed) Not safe. Idempotent DELETE removes resources Not safe. Idempotent

16. Rule # 5 (continued) POST Create a subordinate resource Create child of resource at specified URI Append representation to existing resource Process this Not safe, not idempotent Be careful with this one

17. Demonstrating the ilities of REST Rule # 6: More of the uniform interface constraint Use the HTTP response codes Also part of the uniform interface constraint Theres more than just 200 and 404 Some of the more interesting response codes: (Many work in conjunction with certain HTTP headers. Self descriptive messages constraint) 201: Created (Ive saved your data) 202: Accepted (Message received) 204: No content (The resource is valid, its just empty) 301: Moved permanently (The resource is now over there) 304: Not Modified (Use the representation I gave you earlier) 401: Unauthorized (Who are you? Go away.) 409: Conflict (Im sorry, Dave, Im afraid I cant do that)

18. Demonstrating the ilities of REST Corollary to rules 1 through 6 Do not create one or a few URLs and overload them Client authors can no longer assume HTTP semantics Each URL is essentially accessible via a unique networking protocol If its not on the Web, it doesnt exist POST /expenses HTTP 1.1... placey 123 What is /expenses? What will come back if I GET it? How do I get an expense? How do I create a new one? Can I see all expense data from 2006? Now! Is it safe to GET /expenses/submit? Can I access it twice? Can I link to it? What happens if the POST fails? POST /expenses/submit HTTP 1.1... placey...

19. Demonstrating the ilities of REST Let me show you my RESTful API The ilities will be demonstrated with working code: a simple expense reporting application A REST API that exposes all elements of an expense reporting system as resources Users can create, edit, and delete entire expense reports and individual line items Various views on the data will be allowed For example purposes No management hierarchy (ala Joe approves Sues expense reports) No security

20. Demonstrating the ilities of REST A properly designed Web application is a RESTful API Check out those URLs. Look at the Accept and Content-Type headers. No cookies! How bout some microformats. Revel in the semantically rich source. Hey, alternate formats too. Does it work in Excel? Sure does. Word too? Yup. Command line? You betcha Any others? Sure

21. Demonstrating the ilities of REST Rule # 7 :The hypermedia as the engine of app... Oh, never mind. The hypertext constraint Provide copious links to other related data and guide clients through process flows Allows for URIs to change (though they shouldnt) Allows for clients to dynamically determine what they can do next Allows for clients to discover resources, even those deployed after or indepedent of client development Allows for independence of location and security boundaries

22. Demonstrating the ilities of REST Rule # 7 (continued) Forms with GET actions are links too Consumer requires only a single URI to bootstrap The hypertext representation is the interface! RFC 2616 Client Hypertext URI Resource Adapted from post by Stu Charlton:post by Stu Charlton

23. Demonstrating the ilities of REST Rule # 8: The (session) statelessness constraint Allows you to introduce new resources at will Allows clients to access resources without first establishing a session Rule # 9: The manipulation via representations constraint To alter a resource, send the whole thing Allows client to GET a resource, alter it, and PUT/POST it back Resources can be creates/updated without prior knowledge of message format Rule # 10: Just good advice Avoid object models and schema-based serialization XPath is your friend (not a constraint)

24. Demonstrating the ilities of REST Let me show you my dedicated client The only hard-coded URL is the home page Filling in forms to GET list of resources Following links to GET individual resources Switching content-types in midstream Updating resource by PUTting back the entire representation No session state maintained No serialization, no proxies. The code is fully aware of the network (Well, not really, as I left out all the defensive coding)

25. Demonstrating the ilities of REST Now lets break things Changed every URL Added fields (parameters) to the search form Added new element (total) to expense_reports and expense_report resources: (X)HTML and XML Web and dedicated clients still work! This is not screen scraping If semantic information changes, then create new resources at a new URI http://example.com/v2/... Can use the layered interface constraint to rewrite and route messages on the fly, if possible

26. Demonstrating the ilities of REST And then theres SOAP/WS-* Inaccessible, unevolvable Every endpoint, its own private network The next time someone wants to crunch some numbers in Excel, you can hand them a WSDL, a VBScript Manual, and the SOAP/WS-* specifications. Or you can hand them a URI.

27. Demonstrating the ilities of REST Questions?