the rest architectural style

The REST Architectural Style

Robert Wilson, March [email protected]

Who has heard of REST ?

REST is

• An acronym from: Representational State Transfer • An architectural style that is derived by applying a set

constraints to the elements of a system so the system exhibits certain properties such as loose coupling and scalability

• Defined by Roy T. Fielding, PhD in his PhD dissertation, Chapter 5 Representational State Transfer (REST)

• Data-orientated, “Unlike the distributed object style [31], where all data is encapsulated within and hidden by the processing components, the nature and state of an architecture's data elements is a key aspect of REST” Architectural Styles and the Design of Network-based Software Architectures Roy Thomas Fielding, 2000: PhD dissertation, Chapter 5 Representational State Transfer (REST)

When can I use REST? • For Web Services– build your web service using the REST style– alternative to some of WS-*, not a replacement for WS-*

• Clients interfacing to public REST APIs– e.g. Amazon S3 REST API, Google Data APIs– 63 percent public APIs have a REST like interface

http://www.infoq.com/presentations/Open-API-John-Musser

• From Rich Internet Applications (RIAs)– client sends AJAX requests to a REST interface using a

JavaScript library e.g. jQuery, Dojo (JsonRestStore) or a framework like JavaFX or Silverlight

– response (JSON, XML etc) is displayed on the client

R & R• Resources r– an abstraction of information: a thing, an entity, an event or

“any information that can be named” – identified by URIs, URIs should contain nouns, not verbs

• Representations r – information retrieved from a resource– resource data plus meta-data with control data (in HTTP this

is the message content and headers)– possible in more than one media type, i.e. a resource could

be represented in HTML, XML, JSON, Atom, XHTML or RDF– the current resource state containing data and possibly URIs

(links). The URIs are the relationships and application state transitions available from the current representation

The REST Constraints

• Client-Server architectural style

• Stateless Server– session state is kept on the client

• Cacheable– data is labelled as cacheable or non-cacheable

The REST Constraints cont.

• The Uniform interface is

– “The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components” Architectural Styles and the Design of Network-based Software Architectures Roy Thomas Fielding, 2000: PhD dissertation, Chapter 5 Representational State Transfer (REST)

– for manipulating resources via URIs through a generic set of methods. A uniform interface reduces coupling compared to a services specific interface specification


• The Uniform interface is

– composed of four constraints: identification of resources manipulation of resources through representations self-descriptive messages – meta data & control data hypermedia as the engine of application state - “the

hypertext constraint”, i.e. links in the data for navigation through the application. This is one of the most important constraints


• Layered system

• Code-On-Demand – “optional constraint”

– client functionality extended through download of code or scripts

The constraints will likely have design trade-offs, for example caching may improve performance but decrease reliability

if stale data is served a stateless server can increase information in each

message & you now need to rely on the client to maintain state

Web uniform interface semantics

• RFC2616 specifies HTTP intended method behaviour and semantics for common HTTP methods

• Safe: no side-effects, e.g. does not change resource• Idempotent: “the side-effects of N > 0 identical requests is

the same as for a single request”

Method Operation on the resource Safe Idempotent

POST create a new resource as subordinate No No

GET retrieve a resource representation Yes Yes

PUT modify (update) a resource or create a resource at the id

No Yes

DELETE delete a resource No Yes

Web API using REST principles

1. Define the resources2. Design the resource representations 3. HTTP Protocol considerations

– response status codes– caching strategy– encodings

4. Security

Walk through beginnings of SOFT

• SOFT – Simple Online Family Tree

• Fictitious new web service

• Walk through part of the design of the Web API


1.Define the resources2. Design the resource representations 3. HTTP Protocol considerations


4. Security

SOFT resources

• Candidate resources are:

family-trees mother

family-tree father

people brother

person sister

relations spouse

relation siblings

children

child


1. Define the resources

2.Design the resource representations 3. HTTP Protocol considerations


4. Security

SOFT Resource Representations

• Lets elicit some of them by working through example scenarios of request response messages across the uniform interface

• Our initial URL will be http://soft.example.org/family-trees

• The server will create the hierarchy underneath this URL so client does not need to know the structure as it will be given it by the server in the representations – this avoids coupling between client & server over the hierarchy structure

SOFT Resource Representations• First off create a family-tree with the request:

POST /family-trees HTTP 1.1Host: soft.example.orgContent-Type: application/xmlContent-Length: …

<?xml version="1.0" encoding="UTF-8"?><familyTree xmlns="http://soft.example.org/family-trees" > <name>The Addams Family Tree</name> <createdBy>Gomez Addams</createdBy></familyTree>

• Response:201 Created Location: http://soft.example.org/family-trees/0008Content-Type: application/xmlContent-Length: …

<?xml version="1.0" encoding="UTF-8"?><familyTree xmlns="http://soft.example.org/family-trees" xml:base="http://soft.example.org/family-trees/0008/"> <name>The Addams Family Tree</name> <createdBy>Gomez Addams</createdBy> <link rel="edit" type="application/xml" href="" title="FamilyTree"/> <link rel="related" type="application/xml" href="people" title="People"/></familyTree>

Resource Representations cont.

• In the previous response the link element with the edit attribute is for editing, the href is relative to xml:base (the link element is borrowed from the atom:link element)

• From the previous response using the link element with the title attribute “People”, its relative href & the xml:base attribute we can now create an initial person with the request:

POST /family-trees/0008/people HTTP 1.1Host: soft.example.orgContent-Type: application/xmlContent-Length: …

<?xml version="1.0" encoding="UTF-8"?><person xmlns="http://soft.example.org/family-trees">

<firstName>Morticia</firstName><lastName>Addams</lastName><birth>19800101</birth><sex>F</sex>

</person>


• Response:201 Created Location: http://soft.example.org/family-trees/0008/people/1234Content-Type: application/xmlContent-Length: …

<?xml version="1.0" encoding="UTF-8"?><person xmlns="http://soft.example.org/family-trees"

xml:base "http://soft.example.org/family-trees/0008/people/1234/"><firstName>Morticia</firstName><lastName>Addams</lastName><birth>19800101</birth><sex>F</sex><link rel="edit" type="application/xml" href="" title="Person"/><link rel="related" type="application/xml" href="relations" title="Relations"/>

</person>

• with link elements for editing Morticia and Morticia’s relations

Resource Representations cont.• After creating two extra people who are Morticia’s mother

and brother, add them as relations of Moritica: POST /family-trees/0008/people/1234/relations HTTP 1.1Host: soft.example.orgContent-Type: application/x-www-form-urlencodedContent-Length: …

role=mother&person=http://soft.example.org/family-trees/0008/people/2344

201 Created Location: http://soft.example.org/family-trees/0008/people/1234/relations/motherContent-Length: 0

POST /family-trees/0008/people/1234/relations HTTP 1.1Host: soft.example.orgContent-Type: application/x-www-form-urlencodedContent-Length: …

role=brother&person=http://soft.example.org/family-trees/0008/people/5588

201 Created Location: http://soft.example.org/family-trees/0008/people/1234/relations/brothers/5588Content-Length: 0

Resource Representations cont.• If we GET Morticia’s relations using the edit link from the

initial Post response using:GET /family-trees/0008/people/1234/relations HTTP 1.1Host: soft.example.org

• Response:200 OKLocation: http://soft.example.org/family-trees/0008/people/1234/relationsContent-Type: application/xmlContent-Length: …

<relations xmlns="http://soft.example.org/family-trees"xml:base "http://soft.example.org/family-trees/0008/people/1234/relations/"><link rel="edit" type="application/xml" href="" title="Relations"/><relation role="mother" person="http://soft.example.org/family-trees/0008/people/2234">

<link rel="edit" type="application/xml" href="mother" title="Mother"/></relation><relation role="brother" person="http://soft.example.org/family-trees/0008/people/5588">

<link rel="edit" type="application/xml" href="brothers/5588" title="Brother"/></relation>

</relations>

Resource Representations cont.• Lets modify Morticia’s mother with a PUT request:

PUT /family-trees/0008/people/1234/relations/mother HTTP 1.1Host: soft.example.orgContent-Type: application/x-www-form-urlencodedContent-Length: …

role=mother&person=http://soft.example.org/family-trees/0008/people/5556

• Response:200 OKLocation: http://soft.example.org/family-trees/0008/people/1234/relations/motherContent-Type: application/xmlContent-Length: …

<?xml version="1.0" encoding="UTF-8"?><relation xmlns="http://soft.example.org/family-trees"

xml:base "http://soft.example.org/family-trees/0008/people/1234/relations/mother"role="mother" person="http://soft.example.org/family-trees/0008/people/5556"><link rel="edit" type="application/xml" href="" title="Mother"/>

</relation>


• Lets delete Morticia’s brother with a DELETE request: DELETE /family-trees/0008/people/1234/relations/brothers/5588 HTTP 1.1Host: soft.example.org

• Response:200 OK


1. Define the resources2. Design the resource representations

3.HTTP Protocol considerations– response status codes– caching strategy– encodings

4. Security

SOFT response status codes

• Specify the HTTP method response codes from SOFT

• POST – on success will return 201 Created and the Location:

header will have the URI of the new resource – failure code: 400 Bad Request

• GET– on success will return 200 OK– failure codes: 400 Bad Request, 404 Not Found

SOFT response status codes cont.

• PUT– on success will return 200 OK– failure codes: 400 Bad Request, 404 Not Found, 409

Conflict • DELETE

– on success will return 200 OK– failure codes: 400 Bad Request, 404 Not Found, 410 Gone

• If security is applied and the user is not authenticated then the response is 401 Unauthorised

• see Reference for RFC2616, Ch 10 Status Code Definitions

Consider SOFT’s Caching Strategy

• Cache Topology– Private Caches – in the Web browser– Proxy Caches – proxy server for scalability

• Cache Processing– Server specifies expiration time using Cache-Control

(HTTP/1.1) or Expires (HTTP/1.0) headers– Revalidation using a “conditional GET”, only gets a new

copy of the document if it has changed , client can send either header: If-Modified-Since, send date that client has as Last-

Modified date, only resolution to the second If-None-Match, send the ETag value that was sent

from the server back to the server to see if the cache stale

Consider HTTP Encodings for SOFT

• Content-Encoding, encoding of the data by – compression (gzip ...) , encryption (PGP…)

• Transfer-Encoding, encoding to change the way the data is transferred:– chunked, send the data in chunks , don’t specify a content

length


1. Define the resources2. Design the resource representations 3. HTTP Protocol considerations


4.Security

SOFT Security

• Could use – basic authentication, need to use HTTPS to encrypt the

username password information in the header– digest authentication, MD5 checksum of the username,

password so these are not sent in clear text– HMAC: Keyed-Hashing for Message Authentication, a hash

of selected elements from the request with a secret key, used by Amazon

http://docs.amazonwebservices.com/AmazonS3/2006-03-01/index.html?RESTAuthentication.html

• For information that needs to be secure use HTTPS to encrypt the message which ever method above is used. Note: As HTTPS encrypts the message an intermediary will not know to cache the message, i.e. no caching by intermediaries when using HTTPS

Worked examples

• For other examples see the references

– How to GET a Cup of Coffee by Jim Webber, Savas Parastatidis & Ian Robinson Oct 02, 2008

http://www.infoq.com/articles/webber-rest-workflow

– msdn, A Guide to Designing and Building RESTful Web Services with WCF 3.5, Aaron Skonnard, Oct 2008

http://msdn.microsoft.com/en-us/library/dd203052.aspx

— Using REST to aid WS-* - building a RESTful SOA Registry http://www.infoq.com/presentations/rest-soa-registry

Java Toolkits/Frameworks

Java Community Process - JSR 311: JAX-RS: The JavaTM API for RESTful Web Services, server side specification, annotation based

• Jersey, – Sun production ready reference implementation of JSR311

• RESTlet– early REST framework, implements JSR311 and has its own class based hierarchy

• RESTEasy from Jboss– implements JSR311, also includes a client framework

• Apache CXF 2.1

Java Toolkits/Frameworks cont. • Spring MVC 3.0.0M1

– 3.0.0 is a milestone release, GA in Q2 2009– REST was highly requested as a feature to be included in 3.0 by the Spring user community– 3.0.0 has better support for REST than the current version– can integrate Jersey, RESTEasy, CXF, RESTlet with the current version of Spring

Toolkits/Frameworks

• Microsoft Windows Communication Framework 3.5 (WCF)

• IBM WebSphere sMash – previously know as Project Zero

• Ruby on Rails

Concluding REST• Think of the resources:

1. Any information can be a resource2. Their data format (representations with URIs) and3. Manipulation through a uniform interface

• If REST constraints aren’t needed then don’t worry about them. An API that has all the REST constraints is a RESTful API.

QUESTIONS?

References• Architectural Styles and the Design of Network-based Software Architectures Roy Thomas Fielding, 2000: PhD dissertation,

Chapter 5 Representational State Transfer (REST) , http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm Chapter 6 Experience and Evaluation, http://www.ics.uci.edu/~fielding/pubs/dissertation/evaluation.htm

• RFC 2616 Hypertext Transfer Protocol -- HTTP/1.1 June 1999, R .Fielding et al.

http://www.rfc-editor.org/rfc/rfc2616.txt

• A little REST and Relaxation, Roy T. Fielding, Ph.D.

http://www.slideshare.net/royfielding/a-little-rest-and-relaxation

• IBM, RESTful Web services: The basics by Alex Rodriguez, 06 Nov 2008

http://www.ibm.com/developerworks/webservices/library/ws-restful/index.html

• How to GET a Cup of Coffee by Jim Webber, Savas Parastatidis & Ian Robinson Oct 02, 2008

http://www.infoq.com/articles/webber-rest-workflow

• REST Anti-Patterns by Stefan Tilkov, http://www.infoq.com/articles/rest-anti-patterns

• REST: A Pragmatic Introduction to the Web's Architecture by Stefan Tilkov Jan 29 2009

http://www.infoq.com/presentations/qcon-tilkov-rest-intro

http://www.slideshare.net/deimos/stefan-tilkov-pragmatic-intro-to-rest

• msdn, A Guide to Designing and Building RESTful Web Services with WCF 3.5, Aaron Skonnard, Oct 2008


• Ian Robinson discusses REST, WS-* and Implementing an SOA Jan 26, 2009

http://www.infoq.com/interviews/robinson-rest-ws-soa-implementation

• http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

• http://www.xfront.com/REST.ppt

References cont.• http://www.slideshare.net/ozten/rest-vs-soap-yawn

• http://www.slideshare.net/stevenn/devoxx-2008-rest-in-peace-presentation-831560

• http://www.slideshare.net/sallamar/pragmatic-rest-presentation

• http://www.slideshare.net/guestb2ed5f/scalable-reliable-secure-rest

• http://www.slideshare.net/swamy_g/rest-overview

• http://www.slideshare.net/deimos/steve-vinoski-rest-and-reuse-and-serendipity

• http://www.slideshare.net/calamitas/restful-best-practices

• Code Talks: Demonstrating the "ilities" of REST

http://wanderingbarque.com/presentations/qcon2007.ppt

• http://bitworking.org/news/125/REST-and-WS

• Amazon S3, http://docs.amazonwebservices.com/AmazonS3/latest/RESTAPI.html

• Google Data API, http://code.google.com/apis/gdata/docs/2.0/basics.html

• Yahoo Groups: rest-discuss, http://tech.groups.yahoo.com/group/rest-discuss

• www.infoq.com/rest

• HTTP :The Definitive Guide by David Gourley, Brian Totty

• URI Templates

• http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.html

• http://www.ibm.com/developerworks/web/library/wa-uri/

• http://www.ietf.org/rfc/rfc3986.txt

• http://www.infoq.com/presentations/Open-API-John-Musser

• http://www.infoq.com/presentations/rest-soa-registry

References cont.• Jersey related:

https://jersey.dev.java.net/ http://weblogs.java.net/blog/caroljmcdonald/ http://blogs.sun.com/theaquarium/tags/Jersey

http://wiki.glassfish.java.net/attach/RESTfulWebServicesDevelopersGuide/p6.html

• REST presentation from the Developing Rich Internet Applications with Spring course by SpringSource

• http://www.jroller.com/Solomon/entry/jax_rs_spring_integration

• http://www.codemonkeyism.com/wp-content/uploads/2008/10/web-entwicklung-2008_english.pdf

• http://www.ibm.com/developerworks/library/i-zero1/

• http://hinchcliffe.org/archive/2006/09/10/9275.aspx

• http://www.infoq.com/interviews/Spring-3.0-Rod-Johnson

• How Ruby on Rails and REST go together By Rich Seeley, News Writer 21 May 2008 | SearchSOA.com

http://searchsoa.techtarget.com/news/article/0,289142,sid26_gci1314640,00.html

• Security

HTTP Authentication: Basic and Digest Access Authentication, J .Fransks et al. June 1999

http://www.ietf.org/rfc/rfc2617.txt

http://kswenson.wordpress.com/2008/12/11/rest-assured-oauth-security/


• Atom

The Atom Syndication Format, http://www.ietf.org/rfc/rfc4287.txt

The Atom Publishing Protocol , http://www.ietf.org/rfc/rfc5023.txt

http://www.ibm.com/developerworks/xml/library/x-atom10.html

• ancestry.com.au

THE END

the rest architectural style

Technology

rest interface

resource resource data

rest principles

rest style alternativeto

current resource state

soft resource representations

public rest apis

new resource