All Contents © 2007 Burton Group. All rights reserved. Code Talks: Demonstrating the "ilities" of REST Peter Lacey Senior Consultant [email protected]

All Contents © 2007 Burton Group. All rights reserved.

Code Talks: Demonstrating the "ilities" of REST

Peter LaceySenior [email protected]@wanderingbarque.com

www.burtongroup.comwanderingbarque.com/nonintersecting

Thursday – November 8th, 2007

mailto:[email protected]

mailto:[email protected]

http://www.burtongroup.com/

http://wanderingbarque.com/nonintersecting

http://wanderingbarque.com/nonintersecting

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


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


Constraint Property Trade Off

Client-Server Simplicity, scalability, modifiability

Stateless Scalability, simplicity, reliability, visibility, modifiability Degrades efficiency

Cacheable Scalability, performance Degrades reliability

Uniform Interface Simplicity, visibility, modifiability Degrades efficiency

Layered System Scalability, security, legacy integration, modifiability Adds latency

Identification of Resources Required by uniform interface. Simplicity, scalability, modifiability

Manipulation via representations

Required by uniform interface and stateless. Simplicity, visibility, performance, modifiability

Increases bandwidth

Self-descriptive messages Required 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) Modifiability Reduces visibility

Summary of REST constraints


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


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


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)


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


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”


Rule # 3

• There is, of course, no rule # 3


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


• 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]



• 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


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>

http://microformats.org/


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


• 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


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)


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

POST /expenses HTTP 1.1...<get_expense> <user_id>placey</user_id> <expense_id>123</expense_id></get_expense>

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...<expense> <user_id>placey</user_id> ...</get_expense>


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


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


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 shouldn’t)• 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



• 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

URI

Resource

Resource

Adapted from post by Stu Charlton:

http://www.stucharlton.com/blog/archives/000141.html




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

formatRule # 10: Just good advice

• Avoid object models and schema-based serialization• XPath is your friend• (not a constraint)


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)


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


And then there’s SOAP/WS-*

Inaccessible, unevolvableEvery endpoint, its own private network

The next time someone wants to crunch somenumbers in Excel, you can hand them a WSDL,a VBScript Manual, and the SOAP/WS-* specifications.

Or you can hand them a URI.


Questions?

Documents

All Contents © 2007 Burton Group. All rights reserved. Code Talks: Demonstrating the "ilities" of REST Peter Lacey Senior Consultant [email protected]