all contents © 2007 burton group. all rights reserved. rest easy peter lacey senior consultant...

All Contents © 2007 Burton Group. All rights reserved.

REST Easy

Peter Lacey

Senior Consultant

[email protected]

www.burtongroup.comTuesday – June 26th, 2007

REST Easy

Agenda

• Understanding REST• Using HTTP to build REST Applications• REST concepts and practices• Related technology• REST, WS-*, and SOA• Recommendations

Understanding REST

What is REST? Part 1

“With REST, every piece of information has its own URL.” David Meggison, REST: the quick pitch

Inventor of SAX

“With REST, every piece of information has its own URL.” David Meggison, REST: the quick pitch

Inventor of SAX

Understanding REST


• REST is an architectural style for distributed systems• An architectural style is…

• … a coordinated set of architectural constraints that restricts the roles/features of architectural elements and the allowed relationships among those elements within any architecture that conforms to that style.

— or —• … an abstraction, a design pattern, a way of discussing an

architecture without concern for its implementation.• Music styles: Jazz, Blues (sorta)• Building styles: Baroque, Bauhaus (kinda)• Programming styles: Object oriented, functional, procedural

Understanding 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• REST is not a set of laws or even a specification. It’s a style

“I am a big fan of REST (evangelical even) but I will personally break every single principle of REST to get a job done.” Jon Hanna

“I am a big fan of REST (evangelical even) but I will personally break every single principle of REST to get a job done.” Jon Hanna

• Simplicity • Scalability • Modifiability• Performance

• Visibility (to monitoring)• Portability• Reliability

http://tech.groups.yahoo.com/group/rest-discuss/message/7879

http://tech.groups.yahoo.com/group/rest-discuss/message/7879

Understanding REST

What is REST? Part 3: Representational State Transfer

• Key information (data) abstraction: The Resource• A resource is any information that can be named: documents,

images, services, people, collections, etc.

• Resources have state• State may change over time

• Resources have identifiers (constraint)• A resource is anything important enough to be referenced

• Resources expose a uniform interface (constraint)• System architecture simplified, visibility improved. Encourages

independent evolvability of implementations.

Understanding REST


• On request, a resource may transfer a representation of its state to a client

• Necessitates a client-server architecture (constraint)

• A client may transfer a proposed representation to a resource

• Manipulation of resources through representations (constraint)

• Representations returned from the server should link to additional application state. Clients may follow a proposed link and assume a new state

• Hypermedia as the engine of application state (constraint)

Understanding REST


• Stateless interactions (constraint)• Each request from client to server must contain all of the information

necessary to understand the request, and cannot take advantage of any stored context on the server

• Statelessness necessitates self-descriptive messages (constraint)

• Standard media types• Meta-data and control-data

• Uniform interface + Stateless + Self-descriptive = Cacheable (constraint)

• Cacheable necessitates a layered-system (constraint)

Understanding REST

Constraint Property

Client-Server Separation of concerns: simplicity, scalability, evolvability

Stateless Scalability, reliability, visibility

Cacheable Scalability, performance

Uniform Interface Simplicity, evolvability, visibility

Layered System Scalability, security, legacy integration

Identification of Resources Simplicity, scalability. Required by uniform interface

Manipulation via representations Evolvability. Required by uniform interface

Self-descriptive messages Required by stateless, cachebale, uniform interface, and layered system

Hypermedia as the engine of application state Scalability, reliability, evolvability, performance. Required by uniform interface

Code on demand (optional) Evolvability

Summary of REST constraints

Understanding REST

1. The network is reliable 2. Latency is zero 3. Bandwidth is infinite 4. The network is secure

5. Topology doesn't change6. There is one administrator7. Transport cost is zero8. The network is homogeneous

“There are irreconcilable differences between local and distributed computing” Jim Waldo et al, A Note on Distributed Computing

“There are irreconcilable differences between local and distributed computing” Jim Waldo et al, A Note on Distributed Computing

• You cannot pretend remote objects are in the same address space as local objects.

• The Eight Fallacies of Network Programming

Why bother?

http://research.sun.com/techrep/1994/abstract-29.html

http://research.sun.com/techrep/1994/abstract-29.html

Understanding REST

Why bother?

• Constrained systems emphasize restraint and awareness of the system’s context

• Constraints are the realization of design goals• Unconstrained distributed systems are difficult to use,

brittle, unreliable, and of marginal utility

Understanding REST

What is REST: the answer

REST is a coordinated set of architectural constraints that attempts to minimize latency and network communication while at the same time maximizing the independence and scalability of component implementations. …. REST enables the caching and reuse of interactions, dynamic substitutability of components, and processing of actions by intermediaries, thereby meeting the needs of an Internet-scale distributed hypermedia system. Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures

• Roy is the principal author of the HTTP 1.0, HTTP 1.1, and URI specs• Co-founder of The Apache Software Foundation, co-author of the

original Apache Web Server, author of libwww-perl

http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

REST Easy

Agenda


Using HTTP to build REST Applications

What distributed systems protocol supports the implementation of REST applications?

HTTP 1.1aka RFC 2616

URIs: RFC 3986

MIME: RFCs 2045/2046

Media Types (multiple RFCs, IANA)


What HTTP is not

• Inevitable• Archaic• Poorly designed• Something to be suffered through• A transport protocol• The answer to everything

What HTTP is

• Purposefully designed• REST conformant• Frequently abused• Wildly successful• An application protocol

“Instead of embracing the people, principals, and technologies that gave rise to [the Web, software vendors] have chosen to subvert its history and to implant the ridiculous notion that it is ‘incapable of meeting the stringent demands of the business community.’”

Ryan Tomayko, Motherhood and Apple Pie

“Instead of embracing the people, principals, and technologies that gave rise to [the Web, software vendors] have chosen to subvert its history and to implant the ridiculous notion that it is ‘incapable of meeting the stringent demands of the business community.’”

Ryan Tomayko, Motherhood and Apple Pie


HTTP: A brief introduction

• A stateless, client/server, request/response application protocol

• Clients make requests of servers using four main operations (uniform interface)

• GET, POST, PUT, DELETE (there are others)

• A request is sent to a specified URI (addressabilty)• An HTTP request/response is an envelope.• Inside the envelope are headers followed by a resource

representation—if any (self-descriptive)


Anatomy of an HTTP GET

GET / HTTP/1.1Host: www.burtongroup.comUser-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.3)...Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9...Accept-Language: en-us,en;q=0.5Accept-Encoding: gzip,deflateAccept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7Keep-Alive: 300Connection: keep-aliveCookie: [blah blah blah]Cache-Control: max-age=0[ No entity body ]

HTTP/1.x 200 OKDate: Thu, 17 May 2007 14:06:30 GMTServer: Microsoft-IIS/6.0X-Powered-By: ASP.NETX-AspNet-Version: 2.0.50727Cache-Control: privateContent-Type: text/html; charset=utf-8Content-Length: 16850[ Response follows CRLF ]

HeadersRequestResponseGeneralEntityCustom


Sample Application: A simple expense reporting system

• Design a Web API that exposes all elements of an expense reporting systems

• Users can create, edit, and delete entire expense reports and individual line items

• Various views on the data will be allowed• Users must be authenticated• For example purposes

• Users are not considered resources• No management hierarchy


The REST Recipe

• Find all the nouns• Define the formats• Pick the operations• Highlight exceptional status codes


Find all the nouns

• Everything in a RESTful system is a resource – a noun• If you find yourself creating verbs, noun-ify them

• ApproveExpense ExpenseApprovals

• Every resource has a URI• Ideally just one (but don’t sweat it)

• URIs should be descriptive• http://example.com/expenses;pending

• Not a REST principle, but a good idea• Spend some time here, but don’t agonize over the perfect URI

• URIs should be opaque• automated (non-human) clients should not infer meaning from a URI

• URIs should be cool• Cool URIs don’t change

http://www.w3.org/DesignIssues/Axioms.html#opaque

http://www.w3.org/Provider/Style/URI


Find all the nouns• Use path variables to encode hierarchy

• /expenses/123• Use other punctuation to avoid implying hierarchy

• /expenses/Q107;Q307• /expenses/lacey,peter

• Use query variables to imply inputs into an algorithm• /search?approved=false

• You won’t need query variables as much as you think

• Caches tend to (wrongly) ignore URIs with query variables• URI space is infinite (but URI length is not ~ 4K)• Don’t leak platform information

• /expenses.php/123

/expenses?start=20070101&end=20071231 should be /expenses/20070101-20071231


Resource URI

Bill's expense reports /users/bill/expenses

Expense report #123 /users/bill/expenses/123

All expense reports (you're allowed to see) /expenses/

All pending (new, etc.) expense reports /expenses;pending (new, etc.)

Bill's pending expense reports /users/bill/expenses;pending

Expense 123’s line items /users/bill/expenses/123/line_items

Line item 2 of Expense 123 /users/bill/expenses/123/line_items/2

2006 expenses /2006/expenses/

2006 open expenses /2006/expenses;submitted

Find all the nouns

• Typically expressed as URI Templates• /{expense-id}/{line-item}

• Starter List of Resources (not all inclusive)• Assumes base URI, e.g. http://expenses.example.com/v1

http://bitworking.org/projects/URI-Templates/


Define the formats

• Neither HTTP nor REST mandate a single representation for data

• A resource may have multiple representations• XML, JSON, binary (e.g., jpeg), name/value pairs

• Schema languages are not required (if even possible)• Representations should be well-known media types

(IANA registered MIME types)• Try and use “up-stack” media types

• Makes your resources maximally accessible• XHTML or Atom instead of vanilla XML• You won’t always be able to do this, but you should try


Define the formats

• Expenses (a collection of expense reports)• Will be presented as a list• Summary data only: report_id, submitter, total, status, link to detail

• Therefore, need a format that presents a list of links• How 'bout XHTML!

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN“ "http://www.w3.org...">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">

<head></head>

<body>

<ul class=“expense_reports">

<li><a href="/users/bill/expenses/001">001</a>, Bill Smith, 1000.00, payed</li>

<li><a href="/users/pete/expenses/002">002</a>, Pete Lacey, 1500.00, submitted</li>

...

</ul>

</body>

</html>


Define the formats:

• Even better (tables are understood by spreadsheets)<?xml version="1.0" encoding="UTF-8"?>

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">

<head></head>

<body>

<table class="expenses">

<tr class="expense_report">

<td class=“report_id”>

<a rel=“expense_detail” href="/users/bill/expenses/001">001</a>

</td>

<td class=“submitter”>

<a rel=“employee_detail” href="http://employees.example.com/bsmith">

Bill Smith</a>

</td>

<td class=“amount”>1000.00</td>

<td class=“status”>closed</td>

</tr>

...

</table>

</body>


Define the formats

• 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 a stylesheet 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: <span class="latitude">37.386013</span>, <span class="longitude">-122.082932</span></div>


Define the formats (continued)

• Simple expense item: (straight XML this time)<ExpenseItem> <Date>2007-07-08</Date> <Description>Airfare</Description> <Amount>500.34</Amount> </ExpenseItem>

• Simple expense report: (straight XML this time)<ExpenseReport xmlns:xlink="http://www.w3.org/1999/xlink"> <Submitter xlink:href=“http://employees.example.com/placey”> Peter Lacey </Submitter> <StartDate>2007-07-07</StartDate> <EndDate>2007-07-13</EndDate> <Status>SUBMITTED</Status> [expense items with links] <Total>9,999.99</Total></ExpenseReport>


Pick the operations

• HTTP has a constrained user interface (set of verbs/operations/methods)

• GET• POST• PUT• DELETE• HEAD• OPTIONS (not widely supported)• TRACE (not significant)• CONNECT (not significant)

• All of our resources will support GET


Pick the operations (just GET for now)

“GET is one of the most optimized pieces of distributed systems plumbing in the world ” Don Box (creator of SOAP)“GET is one of the most optimized pieces of distributed systems plumbing in the world ” Don Box (creator of SOAP)

• GET returns a representation of the current state of a resource

• GET is “safe”• Does not change resource state.• May trivially change server side state, e.g. log files

• GET is “idempotent”• Multiple requests are the same as a single request• Might be impacted by concurrent operations

• NEVER violate these rules

http://pluralsight.com/blogs/dbox/archive/2007/03/07/46337.aspx

http://pluralsight.com/blogs/dbox/archive/2007/03/07/46337.aspx


Highlight exceptional status codes

• HTTP has more response codes than 200 and 404 – learn them

• Information: 1xx, Success 2xx, Redirection 3xx, Client Error 4xx, Server Error 5xx

• For GETs we’ll need:• 200 OK• 204 No Content• 404 Not Found• We’ll need more later


REST Frameworks• It is possible and legitimate to build REST systems with any HTTP-

enabled application environment• Servlets, .NET, PHP, etc.

• It’s just not fun• Few frameworks now, but more everyday

• RESTlet (Java, open source)• Ruby on Rails (Ruby, open source)• Django (Python, open source)• CherryPy (Python, open source)• JSR 311/JAX-RS (Java)• Astoria (.NET, Microsoft labs project)• Project Zero (Groovy/PHP, IBM incubator project)• .NET 3.5 (aka Orcas, unreleased)


RESTlet

• An open source Java framework for building RESTful applications

• Akin to the servlet API, but maps directly to REST concepts

• Classes for resources, representations, routers

• Can run standalone or in a servlet engine• Provides a client API too

http://www.restlet.org/


RESTlet Architecture

• Components manage virtual hosts and applications• Applications manage a set of related RESTlets• RESTlets are classes that respond to a uniform interface• RESTlet Framework is composed largely of RESTlets


Component

VirtualHost 1

Application 1

Guard

BusinessResource Domain

ObjectBusinessResource

BusinessResource

DomainObject

VirtualHost N


Router

FinderRoot

Application N

Router

DomainObject

BusinessResource

BusinessResource

DomainObject

Finder

Root



• Representation variants


Content Negotiation

• A single resource can have multiple representations• XML, PNG, JSON, etc.• English, Japanese, etc.

• Client can ask for a particular representations via request headers

Accept: text/xml,application/xml,application/xhtml+xml,

text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5

Accept-Language: en-us,en;q=0.5

Accept-Encoding: gzip,deflate

Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7

• “q” = relative preference (0-1)


Content Negotiation

• Doesn’t work in practice• Most clients don’t expose a means to set Accept headers• Some clients don’t support Accept headers at all

• Best Practice: Use Accept headers and expose the content type in the URI

• http://expenses.example.com/123.xml• http://expenses.example.com/123.xhtml• http://expenses.example.com/123.json• Dots preferred over slashes: http://expenses.example.com/123/xml


Conditional GET

• “Give me a resource representation, but not if it hasn’t changed since last time I asked.”

• Saves bandwidth, client processing, and (possibly) server processing

• Two mechanisms: Last-Modified and ETag

Client ServerGET /expenses;pending

200 OK Last-Modified: Sun, 21 Jan 2007 09:35:19 GMT[response]

GET /expenses;pendingIf-Modified-Since: Sun, 21 Jan 2007 09:35:19 GMT

304 Not Modified


Client ServerGET /expenses;pending

200 OKETag:”some UID”[response]

GET /expenses;pendingIf-None-Match:”some UID”

304 Not Modified

Conditional GET: ETag Mechanism


Conditional GET

• Always support conditional GETs• Servers should use both Last-Modified and ETag• Common to use hashes for Etags• When creating ETags consider the expense of

generating the representation and the ETag• Use “deep” ETags

• Build the notion of “changed” deep into your app• E.g., a timestamp column in the database

“This stuff matters” Joe Gregorio (co-author of Atom and APP)“This stuff matters” Joe Gregorio (co-author of Atom and APP)


Caching

• Caching reduces latency and network traffic• Only (non-SSL) GETs are cached – not POSTs etc.• Two kinds of caches

• Browser (user agent)• Proxy

• Largish sites really should use a caching proxy server• You may be and not even know it• Remember, there can be caches all along the way.

• Your application must know how to control how its content is cached

• Otherwise, defaults may be used• Don’t cache sensitive info


Caching

• Important cache-control headersHeader Property

Expires HTTP date. Hold till expiry

Cache-Control: max-age Seconds. Hold for this amount of time

Cache-Control: s-maxage Seconds. As above, but proxies only

Cache-Control: public Cacheable even if authN required

Cache-Control: no-cache Cacheable, but cache must validate freshness

Cache-Control: no-store Don’t cache

Cache-Control: must-revalidate Do not allow stale representations

Cache-Control: proxy-revalidate As above, but proxies only

• Validate = Conditional GET• Example:

•Cache-Control: max-age=3600, must-revalidate


The Writable Web

• Three principal state changing verbs• PUT: Not safe, idempotent

• Create a new resource at the specified URI• Update existing resource at the specified URI• Typical response: 201 Created or 400 Bad Request

• DELETE: Not safe, idempotent• Remove the resource at the specified URI• Typical response: 200 OK

• POST: Not safe, not idempotent• Create a subordinate resource

• Create child of resource at specified URI• Create new resource from factory resource at specified URI• Typical response: 201 Created + Location or 400 Bad Request

• Append representation to existing resource• “Process this”


The Writable Web:• When creating new resources

• Use POST if the server chooses the URI• Use PUT if the client chooses the URI

• "Process this" • POST does “something” and returns “something”

• Usually masking an RPC call ("overloaded POST")• Don't use casually

• "Process this" POST sometimes valuable: • Resource factories• Sometimes you just want a verb• If you find yourself creating resources that can’t be retrieved with GET,

reexamine your design http://expense.example.com/pay_expense

• But don’t sweat it, if it gets you out of a design jam


The Writable Web

• Some HTTP clients, servers, or middleware don’t understand PUT & DELETE

• Including HTML forms and some firewalls/proxy servers• Valid to overload POST to mimic PUT and DELETE in this case

• Example: POST /123/line+items/2?_method=delete


URI Method Business Operation Return Codes

/users/{uname}/expenses POST Create new expense header 201 Created

400 Bad Request

409 Conflict

404 (User) not found

415 Unsupported media type

405 Method not allowed

/users/bill/expenses/123 POST

PUT

DELETE

Add line items

Update expense header

Delete expense header and line items

201

400, 409, 404, 415

/users/bill/expenses/123/line_items/2 PUT

DELETE

Update line item

Delete line item

204 No Content

400, 409, 404, 415, 405

The Writable Web


Asynchronous Operations

• E.g.: Cut a check for an expense. Check processing system is remote. Accepts requests on a queue.

• Expose the queue as a resource• Use the “202 Accepted” response and create a new “job”

resource for later querying

POST /payment+queue HTTP 1.1Host: expenses.example.com

<representation of a payment>

► 202 Accepted► Location: /payment+queue/4567


Asynchronous Operations

• Poll job resource for status

GET /payment+queue/4567 HTTP 1.1

Host: expenses.example.com

► 200 OK

► Content-Type: text/plain

► queued payment of $100 to Pete Lacey

(later)► dequeued payment of $100 to Pete Lacey

(later)► Check for $100 paid to Pete Lacey


Transactions

• Updating multiple resources atomically• E.g.: Pay an expense: Cut a check, change expense state to “paid”

• May use overloaded POST• Consider using a transaction resource instead

POST /transactions/payment (factory resource)

► 201 Created

► Location: /transactions/payment/3094 (transaction resource)

• The transaction resource subsumes the relevant URI space and provides the transaction’s view of that space


Transactions

• Then PUT/POST/DELETE the first action to the pseudo-resource exposed through the transaction resource

POST /transactions/payment/3094/payment+queue HTTP 1.1


<representation of a payment>

• Repeat as necessary PUT /transactions/payment/3094/expenses/123 HTTP 1.1


<representation of a a paid expense>

• DELETE transaction resource to rollback• PUT to transaction resource to commit PUT /transactions/payment/3094 HTTP 1.1


committed=true


Transactions

• Benefits• Transactions are addressable• Operations are transparent• Can be linked to later• Instant audit trail• Supports multiple participants

GET /transactions/payment/3094

► 200 OK► Content-Type: application/xhtml+xml► ...► <a href=“/payment+queue/4567”>Enqueued payment of $100</a>► <a href=“/expenses/123”>Expense 123</a> Status: Paid</a>► ...


Security

• REST security is Web Security• Authentication

• HTTP Basic• HTTP Digest (not widely supported)• X.509 certificates via SSL

• Encryption and Digital Signatures• SSL (TLS)

• HTTP Basic over SSL preferred


Security

• HTTP Basic too primitive for some situations• SSL not really RESTful

• Makes message opaque to intermediaries (lose self-descriptiveness)• HTTP security is extensible• New security solutions are emerging

• Amazon, Google, X-WSSE• REST does not preclude message-level security, but no standard

mechanism is endorsed• Atom allows encrypted and signed messages, but the information is in the

body and not in the header• HTTPSec

• More work is needed here


Redirection

• Forces client to look somewhere else for a resource• Already seen with the Location header returned from

factory resources• 30x series of return codes are all redirects.

• 301 Moved Permanently• Use this if you change the URI of a resource• Client should persist return value so as not to constantly follow old URI

• 303 See Other• For GET, a good means of canonicalizing URIs

•/users/bill/expenses/123 redirects to /expenses/123• For PUT/POST/DELETE, “operation succeeded see here for result”


Redirection

• 30x series of return codes are all redirects.• 304 Not Modified

• Used with conditional GETs• Resend the ETag header and Cache-Control headers

• 307 Temporary Redirect• For GET, same as 303• For PUT/POST/DELETE, “operation not attempted, resubmit over here”

REST Easy

Agenda


REST Concepts and Practices

Addressability

• Every resource that your application manages should be exposed via a URI

• Every URI you provide is a de facto resource, code accordingly

• The URI space is infinite• Multiple representations of a single resource should be

uniquely addressable• URIs are understood by almost all software• URIs can be: written down, memorized, emailed, IM’d,

bookmarked, piped into other apps• Look at all the URIs in this presentation; much better than OLE.


On Statelessness

• Every request happens in isolation• Client maintains application state• All information required by a resource is in the request• Server does not use information from previous requests

• The possible states of a server are also resources, and have URIs• The 10th through Xth pending expense reports

• /expenses;pending,start=10

• Can be retrieved without first visiting the first page of expenses• No synchronized state needed, e.g. FTP’s “working directory”

• Lights that are on at this moment: /lights/currently_on• Eliminates many failure conditions where clients may perform

operations “out of order”


On Statelessness

• Stateless applications can be load-balanced, partitioned, scaled, cached

• More easily allows for active-active disaster recovery• “Sessions” are to be avoided

• Sessions are servers maintaining client-side state• Message is no longer self-descriptive• Server may respond differently to identical requests based on session

• Server should forget about clients between requests• No cookies• No session keys in URI or request data

• Be very careful if breaking the statelessness constraint• Impacts reliability, scalability, performance


Self-descriptive messages

• Message semantics visible without looking at the message body

• Headers describing messages and content• Statelessness• Standard methods• Standard media types

• Enables support for intermediation• Cache knows it can cache GETs, but not POSTs• Cache knows freshness information• Compression engine can choose best technique for content type• Gateway can reject requests for non-English content

• Intermediation supports scalability


Self-descriptive messages: Representations and media types

• Try and use well-known media types• Makes content more accessible• Part of the self-descriptive messaging constraint

• Avoid creating custom representations• There are too few business-oriented media types today

• Craft business messages into XHTML (microformats)• And/or embed in Atom• There’s nothing wrong with name-value pairs

• Incoming representations should be the same as outgoing representations

• A client should be able to GET, modify, and PUT a document• Server should discard any extraneous data


Hypermedia as the engine of application state

• Application state = the current state maintained on client• Servers maintain resource state

• Hypermedia = links and forms• Following a link is a state transition

• Server provides a new representation, client assumes that state

• The server “guides” the client to new states by providing links inside hypertext representations

• All representations that can contain links should contain links• No links, no Web. No Web, no joy.

• Use links liberally!



• Clients should only follow links provided by the server or constructible via forms

• Links should be “classified” with semantic meaning so a smart client will know what the link points too

• Also helps to loosen the coupling between client and server

(Service version 1)<a class="employee_expenses"

href="/employee+expenses">Employee Expenses</a>

(Service version 2)<a class="employee_expenses"

href="/expenses/employees">Employee Expenses</a>



• Linkful media types (hypermedia) provide for• discovery of capabilities • ordering of interactions (i.e., as presented)• independence of location and security boundaries

• Consumer requires only a single URI to bootstrap• The hypermedia representation is the interface!

Client

Hypermedia

Resource

Resource

URI

URI


The Uniform Interface

• All resources present the same external interface• Creates a network

• Anyone can play to some degree. Encourages network effects• HTTP verbs are constrained in how they impact

resources• Safety (GET)

• Simply: No change to server-side state• Precisely: Client not responsible for changes to server-side state

• Idempotency (PUT, DELETE)• More than one request is the same as one request

• Developer is responsible for assuring these constraints• POST is not constrained


The Uniform Interface

• GET and POST are all you really need to be RESTful• Get state / change state• PUT and DELETE are handy optimizations

• Avoid RPCs disguised as REST• Avoid putting verbs in the URI

• del.icio.us API: https://api.del.icio.us/v1/posts/add

• Avoid adding new HTTP verbs• Avoid overloading POST• Often the way out is to create a new resource at a higher

abstraction


Reliable Messaging

• HTTP is an unreliable protocol• No mechanism for determining if sent message was received

• But GET, PUT, and DELETE are intrinsically reliable• GET is safe and idempotent, call it till you get a response• PUT and DELETE are idempotent, call them till you get a response

• POST is a problem• Not safe or idempotent• A number of solutions have been developed, but none are widely in

use POE, HTTPLR• Standard pattern: POST to or GET from a resource factory, PUT to

the returned resource


Is this RESTful?

• Signs you may be doing something wrong• changing state on GET

• expenses.example.com?action=delete&expense=123

• Clue: There's a verb in the URI• Still RESTful, but probably wrong!

• Exposing just a few URLs and putting verbs in the message body or URI (overloading POST)

POST /expenses<method="approve_expenses"> <expense>123</expense> <expense>456</expense></method>

• Overloaded POST is RESTful, but it's more RESTful if the notion of plentiful, GETable resources is maintained


Is this RESTful?

• You may relax constraints, but do so knowingly• If you really need sessions (you don't), you may use cookies• Why does a representation not have links to other resources?• Can you raise the level of abstraction to get rid of an "action"

resource?• Bad: http://experian.com/check_credit?duns=123• Good: http://experian.com/credit_report/123

• Do you really need a custom header?• Is their a higher level media type you can use?

REST Easy

Agenda


Related technology

Atom

• Atom is an XML vocabulary for describing lists of time-stamped entities

• Entities are anything, not just blog entries

Minimal Atom Entry

<entry>

<title>Pending Expense Report for Peter Lacey</title>

<id>http://expenses.example.com/users/placey/expenses/123</id>

<updated>2007-07-01T18:30:02Z</updated>

<summary>Catalyst Expenses. Week of 6/25/07. $2,000</summary>

</entry>

Related technology

Atom: A longer entry

<entry>

<title>Pending Expense Report for Peter Lacey</title>

<link rel="self" type="application/xml"

href="http://expenses.example.com/users/placey/expenses/123"/>

<link rel="enclosure" type=“application/pdf" length="1337"

href="http://expenses.example.com/users/placey/expenses/123.pdf"/>

<id>http://expenses.example.com/users/placey/expenses/123</id>


<author>

<name>Peter Lacey</name>

<uri>employees.example.com/placey</uri>

<email>[email protected]</email>

</author>

<content type="application/xml">

[[XML Representation of the Expense Report]]

</content>

</entry>

Related technology

Atom Feeds

• Atom entries are collected into feeds

<feed xmlns=“http://www.w3.org/2005/Atom”

xmlns:custom=“http://example.com/2007/expenses”>

<title>Pending Expense Reports</title>

<link href="http://expenses.example.com/expenses;pending"/>


<generator uri="http://expenses.example.com">Expense

Reporting System</generator>

<id>http://expenses.example.com/expenses;pending</id>

<custom:process_by>2007-07-31T11:59:59Z</custom:process_by>

<entry>...</entry>

<entry>...</entry>

<entry>...</entry>

</feed>

Related technology

Atom

• Strongly consider representing resources as Atom entries and feeds

• Atom is broadly and increasingly supported• Atom is a good means of broadcasting event data• Atom is extensible• Atom Feed and Entry envelopes have useful information: IDs,

timestamps, origin addresses, etc.• Atom entries and feeds can be encrypted and signed• Jives well with the use of the Atom Publishing Protocol

Related technology

Atom Publishing Protocol

• A RESTful control flow for publishing and retrieving collections of members (feed of entries)

• Adds a few constraints to REST• Mainly, how to deal with collections

• APP implementations have a “service” document• A list of available collections• Typically served from the “homepage:” http://expenses.example.com

• Non-Atom media types are first-class citizens• Strongly consider APP semantics for applications that

have lists, i.e. most of them• APP clients and servers already available

• http://intertwingly.net/wiki/pie/Implementations

Related technology

GData

• Google Data API• Used by Google to expose programming interfaces to:

• Blogger, Google Base, Google Calendar, Google Spreadsheets, Google Code Search, Google Notebook, Picassa

• GData is an extension of (additionally constrains) APP• Useful model for how you can extend APP

• Formally adds querying (search)• http://expenses.example.com/pending?submitter=Peter%20Lacey

• Adds a new authorization technique

Related technology

Web Application Description Language: WADL

• A REST/HTTP-oriented description language• Analogous to WSDL but very different• The most popular of a variety of REST description languages• Not required, but some people like it• Can be used statically for

• Client/server code generation (don't do this)• Tool support (IDE, BPM, etc.)• Client/server configuration

• Can be used dynamically for• resource representation• embedding in a representation

• Ongoing debate about the value of WADL

Related technology

Simple WADL file

<application> <resources base="http://expenses.example.com/v1/"> <resource path="expenses"> <method name="GET"> <request> <param name="start“ style="matrix" type="xsd:int" default="1"/> </request> <response> <representation mediaType="application/xhtml+xml" element=“html:html"/> <faultstatus="400" mediaType="application/xml" element="expense:Error"/> </response> </method> ... </resource> ... </resources></application>

Related technology

REST Infrastructure

• The Web is REST, REST is the Web• All existing Web infrastructure works with REST• Likely already on premise

• Paid for, installed, managed, and understood• Security

• SSL accelerators, access management (ala Netegrity), federation, single sign-on, firewalls

• Performance• Load balancing (ala Local Director)• Caching engines

• Monitoring and Reporting

Related technology

REST Infrastructure

• A close-up look at Squid• Intelligent, open source cache engine• 12,000 request/second• Routing (URL rewriting)• Intelligent connection handling• Authentication and authorization• Reporting• Application level load balancing• Cache peering• Slashdot/Reddit protection (collapsed forwarding)• Intelligent retry/reroute• Connection pooling• 10 years of real world usage!

REST Easy

Agenda


REST, WS-*, and SOA

Why REST/HTTP is good

• Meets the requirements specified of it:• Scalable, high-performing, evolvable, visible, reliable, simple

• Leverages existing infrastructure• Cache engines, firewalls, SSL accelerators, monitoring, load balancers, etc.

• Reach• Low barrier to entry• Ubiquitous (programming languages, operating systems, servers, browsers,

spreadsheets, news readers, mobile devices, etc.)• Addressable

• Hypermedia and URIs make the Web• Interoperable• Extensible

REST, WS-*, and SOA

Current REST Limitations

• Developer tooling is limited• Requires developers to think differently• Dearth of organized documentation• Security too limited • Some of HTTP's pre-existing syntax• Content negotiation doesn’t quite work• POST is non-idempotent • Support for PUT and DELETE• Could use a PATCH method• Not natively asynchronous• Response messages don’t indicate request

REST, WS-*, and SOA

REST vs SOAP and WS-*

• As a means for building out wide-scale, reusable distributed systems, WS-* is seriously flawed

• Flaw: Undesigned / without constraints• Does not provably exhibit any non-functional requirement (scalability, etc.)

• Empirical evidence suggests this is true• Not scalable or reliable: Can’t be partitioned, not stateless• Not performant: Can’t be cached• Not evolvable

• “Protocol independence is a bug.” (Mark Baker)

• Abuses (tunnels over) HTTP (yet uses the term web services)• Unable to leverage any HTTP benefits• Requires a whole new investment in infrastructure

“Adopting WS-* was always prone to being a faith-based exercise…” Bill de hÓra

“Adopting WS-* was always prone to being a faith-based exercise…” Bill de hÓra

REST, WS-*, and SOA

REST vs SOAP and WS-*

• Flaw: Poorly specified• Too many overly complex specs.• Solving problems no one has: distributed transactions, BPEL• Not very interoperable, even with just SOAP• Married too closely to XML Schema

• Difficult, brittle• Type systems don’t work across languages

• No versioning • Trouble with binary data (SwA, DIME, MTOM)• WSDL is the work of mad men• UDDI: monstrously complex and unsuited for the job it’s deployed to do• WS-Addressing: “URIs done badly”

REST, WS-*, and SOA

REST vs SOAP and WS-*• Flaw: Marketing

• Vendor wars• Over promised, over sold, and over due• Tools encourage backwards (code first) development• Tools discourage use of XML tooling: XPath, XSLT, XQuery, etc.

• Flaw: Every endpoint is its own private network• Clients tightly bound to servers. Not evolvable• No reach, accessible by programmers only (barely) • SOAP resources are not addressable

• Do not enrich the Web. Effectively not there.• No notion of links: No spidering. No search. No bookmarking. No tagging. Etc.• Every end point is a terminal point

• WS-Merits• WS-Security doesn’t suck

REST, WS-*, and SOA

REST and SOA

• SOA is not about technology• WS-*, REST, CORBA, etc. can be used

• Use REST instead of WS-*• Infinitely simpler• More accessible• Leverages existing infrastructure• Actually works• Requires less governance

• SOA leverages a managed communication infrastructure (MCI)• XML gateways, SOA management systems, enterprise service busses

• REST MCI equally available, battle hardened, already in place

REST Easy

Recommendations

• REST should be your default choice for distributed applications• REST is not a silver bullet. Use other solutions (e.g. Message-

Oriented Middleware, WS-*) as requirements call for it• MOM is good• Someday, not today, WS-* may make a "better MOM"

• Use SOAP/WS-* to integrate with existing SOAP/WS-* applications

• NOTE: This positioning is not the official Burton Group positioning (yet)

REST Easy

Conclusion

“Engineer for serendipity.” Roy Fielding

“Engineer for serendipity.” Roy Fielding

REST Easy

References: Blogs

• Web Things by Mark Baker• mnot by Mark Nottingham• Intertwingly by Sam Ruby• BitWorking by Joe Gregorio• Random Stuff by Stefan Tilkov• Paul Downey• Sound Advice by Benjamin Carlyle• Bill de hÓra• Non-Intersecting by Pete Lacey• rest-discuss, Yahoo Groups

REST Easy

References: Books

RESTful Web Services by Leonard Richardson and Sam RubyO’Reilly

all contents © 2007 burton group. all rights reserved. rest easy peter lacey senior consultant...

Documents

restful rest

rest easy agenda

single principle of

big fan of rest evangelical

state state

procedural slide

distributed systems

identifiers constraint