Just relax - take some 90 minutes of ReST

Just relax - take some 90 minutes of ReST Markku Laitkorpi Nokia Research Center 4.10.2007 TUT 1 V1-Filename.ppt / yyyy-mm-dd / Initials Prologue: Why should I care? My WS tools can generate a nice SOAP interface for my underlying service implementation I really like that, it is simple and fast Complexity, brittleness, fallacies of network programming ReST acknowledges that network cannot be abstracted away Inherently RPC regardless of how much you use the document style For scalability and interoperability reasons, ReST promotes ultimate visibility of actions Instructive Hide data, reveal algorithms vs. descriptive Reveal data, hide algorithms Integrating software across the network is the main source of my frustration, and the WS-Hairball does not seem to help ReST is about engineering for serendipity Significant step towards adhoc interoperability Web 2.0 applications are cool Frictionless Web 2.0 necessitates a ReSTful approach ReST is the architectural framework allowing for the Web evolution 2 V1-Filename.ppt / yyyy-mm-dd / Initials

ReST background Side-product of Roy Fielding s PhD dissertation (2000): Architectural Styles and the Design of Network-based Software Architectures Thesis: architectural framework illustrating how Principled Design is used to describe an architecture to identify existing problems in an architecture to compare alternative solutions in architecture development to ensure that architecture extensions do not violate the core constraints Representational State Transfer (ReST): a concrete example of an architectural style for network-based systems Set of architectural elements and constraints that induce the selected set of architectural properties for such a system Derived from the distributed hypermedia on the World Wide Web 3 V1-Filename.ppt / yyyy-mm-dd / Initials Architectural style A named, coordinated set of architectural constraints that restricts the features of architectural elements and the allowed relationships among those elements within any architecture that conforms to that style -- Roy Fielding Inducing (and maximizing) the values of the desired set of system attributes, i.e. architectural properties Establishes shared understanding on how things should work spontaneously together makes everybody drive to the same direction by default Architecture is an instance of a particular architectural style 4 V1-Filename.ppt / yyyy-mm-dd / Initials

Must-reads for wanna-be-restafarians Academia Roy Roy Fielding: Architectural Styles Styles Books and and the the Design Design of of Network-based Software Architectures Rohit RohitKhare: Extending the the ReST ReST Architectural Style Stylefor for Decentralized Systems (Google will give you the links ) 5 V1-Filename.ppt / yyyy-mm-dd / Initials Wikis, Fora, Blogs RestWiki rest-discuss on Yahoo!Groups Mark Baker Benjamin Carlyle Duncan Cragg Mark Nottingham Joe Gregorio Sam Ruby Stefan Tilkov Technologies Architecture of the WWW HTTP, URI, MIME, Media types Atom Syndication Format Atom Publishing Protocol Word #1 of the day Serendipity www.thefreedictionary.com: 1. The faculty of making fortunate discoveries by accident. 2. The fact or occurrence of such discoveries. 3. An instance of making such a discovery. Human Web serendipity: Browser & HTTP GET >> PUT http://veikkaus.fi/vakio/39/chelsea_fulham >> Content-type: text/plain >> >> 1 << 200 OK >> PUT http://military.us.gov/defcon >> Content-type: text/plain >> >> 1 << 200 OK 6 V1-Filename.ppt / yyyy-mm-dd / Initials

ReST what it is Architectural style for the software-driven Web Web as a platform for network-based applications Human Web is a subset of the software-driven Web Elements Data: RESOURCES Constraints CLIENT-SERVER, CACHEABLE, STATELESS, LAYERED, UNIFORM INTERFACE Optional: CODE-ON-DEMAND Principled Design: toolbox for architects and developers Quest for network effect / Metcalfe s law Engineering for serendipity With ReST, every piece of information has its own URI -- Elevator pitch by David Megginson 7 V1-Filename.ppt / yyyy-mm-dd / Initials and what it is not Architecture Web architecture is an instance of ReST Technology For the Web architecture, use: HTTP, URI, MIME types, Standard or specification For the Web technologies, read: RFC 2616, RFC 3986, RFC 2045, RFC 2046, Set of laws Know your requirements relax the constraints appreciate the implied costs Silver bullet Principled Design: recognize the set of architectural properties for your system End of the road Extensible by adding new constraints a new architectural style E.g. AR-REST-ED by Rohit Khare asynchronous, routed, estimated, delegated 8 V1-Filename.ppt / yyyy-mm-dd / Initials

Resource Key abstraction for information: conceptual mapping to a set of values that constitute the state for a certain real-world entity Anything that can be named and addressed (standard address mechanism!) Each name is associated with exactly one resource the semantics of this association should remain unchanged over time Two resources are same only if their addresses are same Two resources may overlap with each other Examples http:// /project-plan/latest http:// /project-plan/2007-10-04 Not to be seen or manipulated directly, only by transferring representations Representation: sequence of bytes capturing current or intended state of a resource Content types (MIME types) in HTTP 9 V1-Filename.ppt / yyyy-mm-dd / Initials Resources and the real world Application layer Service Consumer State assertion State snapshot HTTP: ReSTful access layer Representations URIs Representations Service Provider State change Resource layer layer State capture Real-world layer layer 10 V1-Filename.ppt / yyyy-mm-dd / Initials

Constraints in ReST Client-server Statelessness + server simplicity + scalability + reliability + UI portability - efficiency + server simplicity + multiple org. domains (- asymmetric interactions) Cacheability + decreased avg. latency + efficiency + scalability - reliability Uniform interface Layered system + shared caching + legacy encapsulation + scalability + load-balancing + client simplicity - increased avg. latency (Code-ondemand) + client simplicity + extensibility - visibility + visibility + evolvability + impl. decoupling - efficiency 11 V1-Filename.ppt / yyyy-mm-dd / Initials Statelessness Each individual interaction takes place in isolation Different types of possible state Request state between a request and its response(s) Resource state actual information persistence Interaction/Application/Session state client-specific processing flow What about a shopping cart? Either a application state (client-side concept) server OK server OK server NOT OK Client constructs a full cart and uploads it to the server or a resource (server-side concept for the shared state) Shopping cart becomes a part of the shared state and has a URI Links guiding the client how the cart could be processed further: finding new items to add, browsing and removing current items, transforming the cart into a new order, etc. 12 V1-Filename.ppt / yyyy-mm-dd / Initials

Uniform interface Expectations on the outcome of a particular operation should remain the same from one resource to any other resource Standard addressing of resources One universal identifier mechanism that links disparate resources together Exchange of resource representations by a fixed set of operations Operational expectations should be independent from the target resource Self-descriptive messages Follow your nose : message intent can be determined from the envelope Hypermedia as the engine of application state Representations contain links to next possible application states Analogy: think of a Web page as an embodiment of one steady application state Make your resources connected avoid becoming the Dark Matter of the Internet 13 V1-Filename.ppt / yyyy-mm-dd / Initials Visibility of actions Protocol-level, resource-independent information about actions and their related behavior Clients can make uniform expectations on their actions Smart intermediaries can be deployed independently One of the most important factors of serendipity! Visibility of information resource addressing Visibility of operation semantics standard operations Visibility of protocol dependencies and relationships self-descriptiveness Visibility of choreographies and state machines - hypermedia 14 V1-Filename.ppt / yyyy-mm-dd / Initials

Making your first ReSTful service Model the resources Find the nouns and their relationships Realize the interaction architecture operations URIs: Design the URI space for the resources HTTP methods: Select available operations for each URI MIME types: Select relevant representations Add hyperlinks to connect your resources Embedded links in suitable representations hyperlinks things content types Relax the constraints that do not match your requirements 15 V1-Filename.ppt / yyyy-mm-dd / Initials Challenges in resource modeling URI hierarchy, URI opacity, human guesswork URIs are just names vs. intuitive intepretation /a/b /a No requirements for programmatic URI parsing Resource granularity, resource clusters GET vs. PUT: balance between read and write operations Heterogeneous content types: XML and JPEG, for example HTTP headers vs. URIs Client capabilities vs. separate URIs Query string and caching One URI for one thing URI resource mapping should be the same for everyone Layering for scalability: access control and content retrieval Do not sweat for the perfect design But recognize and appreciate the cost of tradeoffs 16 V1-Filename.ppt / yyyy-mm-dd / Initials

Simple example: LightBulb service http:// /lightbulb;info GET text/html http:// /lightbulb GET PUT text/plain application/lightbulb+xml text/plain application/lightbulb+xml >> GET http:// /lightbulb;info >> Accept: text/html << 200 OK << Content-type: text/html << << [HTML form that links to the possible state changes] >> PUT http:// /lightbulb >> Content-type: text/plain >> >> on << 200 OK >> GET http:// /lightbulb >> Accept: application/lightbulb+xml << 200 OK << Content-type: application/lightbulb+xml << << <lightbulb> << <state>on</state> << </lightbulb> 17 V1-Filename.ppt / yyyy-mm-dd / Initials Word #2 of the day Idempotent Mathematical definition for an idempotent function f: 1. f(f(x)) = f(x). www.thefreedictionary.com: 2. An operation that produces the same results no matter how many times it is performed. Built-in reliability: keep retrying until you get a response 18 V1-Filename.ppt / yyyy-mm-dd / Initials

Most relevant HTTP operations HTTP is designed to be your application layer protocol! GET PUT Retrieve a resource representation Clipboard COPY Safe & idempotent Rewrite a complete resource Clipboard PASTE OVER Idempotent DELETE Remove the connection between a resource and its URI Clipboard CUT (no return value) Idempotent POST(a) Append to a resource ( 200 OK ) Create a subresource ( 201 Created ) Clipboard PASTE AFTER POST(p) Process this 200 OK means stuff done Should be avoided (less visibility) POST(t) Protocol tunneling a big no-no 19 V1-Filename.ppt / yyyy-mm-dd / Initials Content types Try not to define a new content type for each new application Content types should be descriptive enough Decisions on processing and dispatching should be based on the envelope Avoid content sniffing requirements for parsing and additional processing application/xml does not tell anything about the actual content application/invoice+xml is much better Content types are versionable: application/invoice2+invoice+xml However, XML is not the center of the universe Natively binary data should be treated as binary for efficiency Multiple representations and content negotiation Each resource may expose one or more representations with different content types Client may negotiate (HTTP headers) on the content type for the best experience Primary principle: single URI for a single concept http://.../project-plan On the other hand: direct URI access for less capable clients http://.../project-plan.xml 20 V1-Filename.ppt / yyyy-mm-dd / Initials

Frequently asked questions Sessions & cookies You don t really need them But browsers & JavaScript? Security HTTP authentication framework No standard for message-level security WS-Security actually has some reusable solutions Transactions Critical sections as resources Dining philosophers in ReST! Reliable messaging Idempotency Empty POST+PUT, POST-once-exactly, Asynchronous operations Queues with 202 Accepted responses, polling for results Conditional retrieval/update Avoid receiving anything that you already have Detecting lost updates ETag, Last-Modified If-None-Match, If-Modified-Since Service descriptions $100M question: Why d you need them? 1. Constructing an invocation NO 2. Discovery MAYBE 3. Data interop YES 21 V1-Filename.ppt / yyyy-mm-dd / Initials Service descriptions? Intent? Resource URI http://.../lightbulb Content type application/lightbulb+xml Application layer layer State assertion State snapshot Assertion <lightbulb> <state>on</state> </lightbulb> HTTP: HTTP: ReSTful access access layer layer Representations URIs Representations Resource layer layer Resource URI http://.../lightbulb Content type application/lightbulb+xml State change State capture 22 V1-Filename.ppt / yyyy-mm-dd / Initials? Impact Real-world layer layer

Some acid tests for ReSTfulness Can you bookmark this application state, email the link to yourself, and continue tomorrow? Can you just simply retry after a network fault? Can you blindly continue using this service after I have replaced and rebooted the server machine at any time Can you expect to do this same thing over there, too? Can you see what is happening to this resource? Can you follow your nose without sticking it too deep? Can you traverse from one thing to another? Are your URIs cool and still refer to the same thing after next upgrade? After 10 years? 23 V1-Filename.ppt / yyyy-mm-dd / Initials Good examples of ReSTful APIs Atom Publishing Protocol a.k.a. APP a.k.a. AtomPub Quite many blogging sites Google Data API http://code.google.com/apis/gdata/protocol.html Amazon S3 http://s3.amazonaws.com/doc/s3-developer-guide/index.html Numbler http://numbler.com/apidoc Really good ReSTful APIs (beyond the APP) are still hard to find good APIs depend on useful content types? 24 V1-Filename.ppt / yyyy-mm-dd / Initials

Bad and ugly examples of ReSTful APIs GET http://api.flickr.com/rest/?method=flickr.photos.getwithgeodata POST http://api.flickr.com/rest/?method=flickr.photos.addtags& photoid=15& tags=helsinki This kind of API often advertises itself as ReSTful In the worst case, this kind of APIs treat GET and POST interchangeably Verdict: ReSTful by accident (for retrieval methods), or not ReSTful at all These should be called SHARE or STREST or HTTP+POX APIs Visibility? Interoperability? 25 V1-Filename.ppt / yyyy-mm-dd / Initials ReST tools RESTlets (Java) server (+ client) JSR311/JAX-RS (Java) server Ruby on Rails (Ruby) server (+ client) Django (Python) server CherryPy (Python) server Project Zero (Groovy, PHP, ) server Astoria (MS.NET) server Orcas/.NET 3.5 (MS.NET) server 26 V1-Filename.ppt / yyyy-mm-dd / Initials

Question time Where do you want to take a ReST today? 27 V1-Filename.ppt / yyyy-mm-dd / Initials