1. The document reports on research into REST and its potential application in the company's reference architectures. It aims to facilitate discussion by reaching a common understanding of REST concepts and principles. 2. It provides an overview of the key concepts in REST including resources, representations, state, and the uniform interface using HTTP methods. It also discusses RESTful web services and when they may be suitable compared to SOAP-based services. 3. The document concludes by discussing how REST and RESTful approaches relate to service-oriented architectures, noting that a RESTful SOA combines the lightweight aspects of REST with the basic concepts of centralized, reusable services in a SOA.

1. 1Public and Informational
REST and Beyond
Ming Yuan
Lead Java Architect
Application, Integration and Development Architecture
November 2008

2. 2
Objectives
Report findings from a research on REST to the Framework team
Reach a common understanding of REST concepts and principles so as to
facilitate exploratory discussion around its place in our reference
architectures
Public and Informational

3. 3
Getting Started
Public and Informational

4. 4
REST – The Term
Standing for REpresentational State Transfer
Coined by Roy Fielding in his Ph.D. dissertation at 2000
Describing an architecture style of networked systems
Public and Informational

5. 5
Resources
A resource is anything that’s important enough to be
referenced as a thing in itself
A resource may be a physical object (a document), or an
abstract concept (courage)
A resource has to have at least one URI. The URI is the
name and address of a resource
A resource can be stored as a stream of bits
Public and Informational

6. 6
Representations – ( the “RE” in REST )
A representation is the document conveying the
information about the current state of a resource
A resource is retrieved not just as a raw data – (e.g.
character string or a BLOB) but as a complete
representation of a physical or logical entity
By “complete representation” we mean that consumers of a resource
understand how to interpret that representation
Examples
If a consumer is a person – a resource might represented as an HTML
web page.
If a consumer is a server – a resource might represented as a XML
file.
Most resources have only one representation; but they may have as many
representations as clients need
Public and Informational

7. 7
State – ( the “S” in REST )
Resource State
Resource state is the representation of the values of the properties of
a resource
State can be described as the content of a resource itself at any given point in
time, or the properties necessary to identify, locate or obtain a resource (or set
of resources)
Resource state is the kind that the “S” in REST refers to
Application State
Application state is the information necessary to understand the context of an interaction
Application state is maintained by being transferred from clients to servers and back to clients
The “stateless” constraint means that all messages between clients and servers must include
complete application state for the context of the exchange – (i.e. no additional information
outside of the exchanged resources is necessary -- “no state left behind”)
Public and Informational

8. 8
REST in a nutshell
Resources can be identified by uniform resource
identifiers (URIs)
Resources can be manipulated via modification of their
representations – (not changing the representation
definition)
Each request is self-descriptive and stateless
Hypermedia as the engine of application state
Public and Informational

9. 9Public and Informational
The term ‘REST’ is relatively new. The technologies
behind REST are not.
REST is not a standard itself, but it does leverage
standards:
HTTP
URI/URL
XML/HTML/GIF/JPEG/etc (Resource Representations)
text/xml, text/html, image/gif, image/jpeg, etc (MIME
Types)
REST – An Architecture Style

10. 10
REST & Web Services
RESTRESTfulful Web ServicesWeb Services
Public and Informational

11. 11
Good things about RESTful web services
Platform-independent
Programming language independent
Standards-based
Can be easily used in the presence of firewalls
Constitutes a lightweight approach to web services
Public and Informational

12. 12
RESTful Web Services Characteristics
Cache:
responses must be capable of being labeled as cacheable or non-cacheable to improve
network efficiency
Uniform interface:
all resources are accessed with a generic interface (e.g., HTTP GET, POST, PUT, DELETE)
Named resources:
the system is comprised of resources which are named using a URL
Layered system:
intermediaries, such as proxy servers, cache servers, gateways, etc, can be inserted
between clients and resources to improve system scalability
Client-Server
consuming components pull representations – A pull-based
interaction style
Stateless:
each request from client to server must contain all the information
necessary to understand the request, and cannot take advantage of
any stored context on the server
Public and Informational

13. 13
When to use RESTful web services
The web services are completely stateless
A caching infrastructure can be leveraged for performance
The service producer and service consumer have a mutual understanding
of the context and content being passed along
Bandwidth is particularly important and needs to be limited, e.g. PDAs or
mobile phones
Web service delivery or aggregation into existing web sites can be enabled
easily with a RESTful style
Public and Informational

14. 14
When Not to use RESTful web services
When a formal contract must be established (and
published) to describe the interface that the web service
offers – (e.g. a WSDL is required to describe the contract)
When the architecture must address complex non-
functional requirements – (e.g. Transactions, Security,
and Trust)
The architecture needs to handle asynchronous
processing and invocation
Public and Informational

15. 15
Principles of RESTful Web Service Design
Categorize your resources according to whether clients can just receive a representation of
the resource, or whether clients can modify (add to) the resource – (i.e. “read-only” vs.
CRUD)
All resources accessible via HTTP GET should not cause side-effect. The resource should just
return a representation of the resource. In other words – simply obtaining a resource does
not affect state of the resource provider – (unlike HTTP POST for example)
Design to reveal data gradually: Contain data volume by exchanging data relevant only to
the context of the current request.
Specify the format of request & response data using a schema (DTD, or W3C Schema)
Describe how your services are to be invoked using either a WADL document, or simply an
HTML document
The key to creating Web Services in a REST network (i.e., the Web) is
to identify all of the conceptual entities that you wish to expose as
services
Create a URL to each resource. The resources should be nouns, not
verbs. For example, do not use this:
http://www.parts-depot.com/parts/getPart?id=00345
Note the verb, getPart. Instead, use a noun:
http://www.parts-depot.com/parts/00345
Public and Informational

16. 16
Case Study:
RESTful Web service in the AIC Java framework
A RESTful web service endpoint is part of the hover-over-help component.
onMouseOver(..)
Invoke REST call
Client script parses REST response
GET /msgsvc/msgid/1 HTTP/1.1
Host: www.aserver.allstate.com
From: yourmachine.allstate.com
User-Agent: HTTPTool/1.1
[blank line here]
HTTP/1.1 200 OK
Date: Fri, 31 Dec 2008 23:59:59 GMT
Content-Type: text/html
Content-Length: 1354
<mouseovermsg>
<connectid>Retention</connectid>
<bkgdcolor>blue01</bkgdcolor>
<msgtitle>Recognition Loss Ratio</msgtitle>
<msgcontent>
Definition adn caculattion for
Regcognition Loss Ratio
</msgcontent>
</mouseovermsg>
Public and Informational

17. 17
Resource Oriented Architecture (ROA)
ROAROA
Resource-OrientedResource-Oriented
ArchitectureArchitecture
Public and Informational

18. 18
ROA – Four Concepts
Resources – (as defined earlier)
Their names (URIs)
Their representations
The links between them
Public and Informational

19. 19
ROA – Four properties
Addressability: Resource identity and location
must be known
Statelessness: No application state is maintained
across requests
Connectedness: Links or forms connect resources
to each other
A uniform interface: A finite and universal set of
available operations – (i.e. “verbs” – see next slide)
Public and Informational

20. 20
ROA – Four Verbs should be used
GET to retrieve information
POST to add new information, showing its relation
to old information
PUT to update information
DELETE to discard information
Public and Informational

21. 21
ROA – Documenting a REST service
WADL – Web Application Description Language
* The WADL schema is owned by W3C, however it’s not yet widely adopted.
<method name="GET" id="ItemSearch">
<request>
<param name="Service" style="query" fixed="AWSECommerceService"/>
<param name="Version" style="query" fixed="2005-07-26"/>
<param name="Operation" style="query" fixed="ItemSearch"/>
<param name="SubscriptionId" style="query" type="xsd:string" required="true"/>
<param name="SearchIndex" style="query" type="aws:SearchIndexType" required="true">
<option value="Books"/>
<option value="DVD"/> <option value="Music"/>
</param>
<param name="Keywords" style="query" type="aws:KeywordList" required="true"/>
<param name="ResponseGroup" style="query" type="aws:ResponseGroupType" repeating="true">
<option value="Small"/>
<option value="Medium"/>
<option value="Large"/>
<option value="Images"/>
</param>
</request>
<response>
<representation mediaType="text/xml" element="aws:ItemSearchResponse"/>
</response>
</method>
Public and Informational

22. 22
The Generic ROA Procedure
Public and Informational

23. 23
Advantages of ROA
Ease of Implementation
Agility of the design.
The lightweight approach
Improved Performance
Better cache support
Lightweight requests and responses
Easier responses parsing
Public and Informational

24. 24
A system design pattern: ROA + SOA
Problem Domain: The UI layer components are tied to the
interfaces in the business layer.
Solution pattern:
Domain objects
Service Interfaces
Public and Informational

25. 25
REST, Web Services & Application Architecture
RESTRESTfulful SOASOA
Public and Informational

26. 26
RESTful SOA
SOA + lightweight technology of REST
Follows the basic concepts of SOA
Extract services from existing or new applications
Centralize them to be consumed by many clients
Can be migrated to the SOAP-based SOA later when your requirement
grows in complexity or scale
Public and Informational

27. 27
Recap
ROAROA
Resource-OrientedResource-Oriented
ArchitectureArchitectureRESTRESTfulful Web ServicesWeb Services
SOAP-based SOASOAP-based SOA
RESTRESTfulful SOASOA
Public and Informational

28. 28
References
RESTful Web Services
BY LEONARD RICHARDSON, SAM RUBY
MAY 2007
"Every developer working with the Web needs to read this book." -- David Heinemeier Hansson, creator of the Rails framework
"RESTful Web Services finally provides a practical roadmap for constructing services that embrace the Web, instead of trying to route around
it." -- Adam Trachtenberg, PHP author and EBay Web Services Evangelist
You've built web sites that can be used by humans. But can you also build web sites that are usable by machines? That's where the future
lies, and that's what RESTful Web Services shows you how to do. The World Wide Web is the most popular distributed application in history,
and Web services and mashups have turned it into a powerful distributed computing platform. But today's web service technologies have
lost sight of the simplicity that made the Web successful. They don't work like the Web, and they're missing out on its advantages.
This book puts the "Web" back into web services. It shows how you can connect to the programmable web with the technologies you already
use every day. The key is REST, the architectural style that drives the Web. This book:
•Emphasizes the power of basic Web technologies -- the HTTP application protocol, the URI naming standard, and the XML markup language
•Introduces the Resource-Oriented Architecture (ROA), a common-sense set of rules for designing RESTful web services
•Shows how a RESTful design is simpler, more versatile, and more scalable than a design based on Remote Procedure Calls (RPC)
•Includes real-world examples of RESTful web services, like Amazon's Simple Storage Service and the Atom Publishing Protocol
•Discusses web service clients for popular programming languages
•Shows how to implement RESTful services in three popular frameworks -- Ruby on Rails, Restlet (for Java), and Django (for Python)
•Focuses on practical issues: how to design and implement RESTful web services and clients
This is the first book that applies the REST design philosophy to real web services. It sets down the best practices you need to make your
design a success, and the techniques you need to turn your design into working code. You can harness the power of the Web for
programmable applications: you just have to work with the Web instead of against it. This book shows you how.
Public and Informational

29. 29
References
SOA – Using Java Web Services
BY Mark D. Hansen
MAY 2007
SOA Using Java™ Web Services is a hands-on guide to implementing Web services and Service Oriented Architecture (SOA) with today’s Java
EE 5 and Java SE 6 platforms. Author Mark Hansen presents in explicit detail the information that enterprise developers and architects need
to succeed, from best-practice design techniques to state-of-the-art code samples.
Hansen covers creating, deploying, and invoking Web services that can be composed into loosely coupled SOA applications. He begins by
reviewing the “big picture,” including the challenges of Java-based SOA development and the limitations of traditional approaches. Next, he
systematically introduces the latest Java Web Services (JWS) APIs and walks through creating Web services that integrate into a
comprehensive SOA solution. Finally, he shows how application frameworks based on JWS can streamline the entire SOA development process
and introduces one such framework: SOA-J.
The book
•Introduces practical techniques for managing the complexity of Web services and SOA, including best-practice design examples
•Offers hard-won insights into building effective SOA applications with Java Web Services
•Illuminates recent major JWS improvements–including two full chapters on JAX-WS 2.0
•Thoroughly explains SOA integration using WSDL, SOAP, Java/XML mapping, and JAXB 2.0 data binding
•Walks step by step through packaging and deploying Web services components on Java EE 5 with JSR-181 (WS-Metadata 2.0) and
JSR-109
•Includes specific code solutions for many development issues, from publishing REST endpoints to consuming SOAP services with
WSDL
•Presents a complete case study using the JWS APIs, together with an Ajax front end, to build a SOA application integrating Amazon,
Yahoo Shopping, and eBay
•Contains hundreds of code samples–all tested with the GlassFish Java EE 5 reference implementation–that are downloadable from
the companion Web site, http://soabook.com.
Public and Informational

30. 30
References
Roy Fielding’s dissertation --
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
Dr. Roy Fielding’s Blog -- http://roy.gbiv.com/untangled
Dr. M. Elkstein’s Blog -- http://learn-rest.blogspot.com/
IBM developerWorks -- http://www-128.ibm.com/developerworks
Online article --
http://java.sun.com/developer/technicalArticles/WebServices/restful/
Online article -- http://www.xfront.com/REST-Web-Services.html
Online article -- http://www.xml.com/pub/a/2004/08/11/rest.html
JSR 311: JAX-RS: The Java API for RESTful Web Services --
http://jcp.org/en/jsr/detail?id=311
Public and Informational