Code Talks: Demonstrating the "ilities" of REST

1. 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 8th, 2007

2. Demonstrating the “ilities” of REST • Who am I? • I am not an analyst! • I am a consultant in Burton Group’s Application Platform Strategies service • I’ve 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 Summary of REST constraints

5. Demonstrating the “ilities” of REST • What I’ll 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 I’ll 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 application’s 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, IM’d, 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 don’t 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: • <span class="amount">1000.00</span> • And • <amount>1000.00</amount> • 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/ • 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 <div class="geo">GEO: latitude: <span class="latitude">37.386013</span>, longitude: <span class="longitude">-122.082932</span> </div>

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, it’s your (the resource owner’s) 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 • There’s 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 (I’ve saved your data) • 202: Accepted (Message received) • 204: No content (The resource is valid, it’s 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 (I’m sorry, Dave, I’m afraid I can’t 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 it’s not on the Web, it doesn’t exist • 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 HTTP 1.1 ... <get_expense> <user_id>placey</user_id> <expense_id>123</expense_id> </get_expense> POST /expenses/submit HTTP 1.1 ... <expense> <user_id>placey</user_id> ... </get_expense>

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 Sue’s 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 clients to dynamically determine what they can do next • Allows for URIs to change (though they shouldn’t) • Allows for clients to discover resources, even those deployed after or independent of client development • Allows for independence of location and security boundaries

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

23. Demonstrating the “ilities” of REST • Rule # 8: The stateless communication 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 there’s 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?