Christopher Bartling
Nick Spilman
Kevin Hakanson

Basic REST concepts

Defining your Resource-oriented architecture

HTTP status codes and error handling

Content-type negotiation

Using AJAX with REST

Versioning REST APIs

Caching and other performance

considerations

REpresentational State Transfer

Architecture style or design criteria

 Not a standard
Stateless, client-server, cacheable

communications protocol
Use HTTP requests to post, read, and delete

data.
Lightweight

Nouns as URI, verbs as HTTP method


Resource

 Anything that important enough to be referenced
in its singularity
 Can be physical object or an abstract concept
 Every resource has at least one name
Resources can be a container of other

resources
 Containers are always resources
 Composite design pattern

Resource representation

 Any useful information about the state of a
resource
 Specified through distinct URI or content
negotiation through headers
Canonical resource URI

 Independent of format or locale language
 Can be specified in Content-Location response
header of representation response

GET

http://www.example.com/v1/hr/employees/19328389
POST

http://www.example.com/v1/hr/employees
DELETE

http://www.example.com/v1/hr/employees/14283949
PUT

http://www.example.com/v1/hr/employees/13448784

Addressability

 Resources are identified by URIs
Statelessness

 No connection state maintained between REST
invocations
Connectedness

 Resources should link together in their
representations
Uniform interface

 HTTP GET, PUT, POST, DELETE, HEAD, OPTIONS
 HTTP method header
 HTTP status codes

The name and address of a resource

 The scoping information to resources
 Principle of addressability
Should be descriptive

Unique URIs are exposed for every resource

available from a RESTful system
 Every URI designates exactly one resource
URIs are discoverable by your clients


No state stored on the server

Every HTTP request executes in complete

isolation on the server
Simpler to design and evolve

Easier to scale

Avoid using HTTP sessions and cookies

No side-effects


Standardized

 GET
 POST
 PUT
 DELETE
 HEAD
 OPTIONS
Represents invocation action

Resources expose uniform interface


Primary means of reporting the outcome of a

REST operation
 Use the entity-body to add ancillary qualifiers to
the outcome
 Do not send back resource representations for
anything other than GET—negative impact on
performance optimizations
See Appendix B of RESTful Web Services

book for top 42 HTTP status codes

GET and HEAD requests should not cause any

disastrous changes to the server-side
No side effects!

 Client should not be making requests just for the
side effects
Avoid exposing unsafe operations through

GET

Multiple invocations of an operation results in

the same result state as a single invocation
Idempotent methods: GET, HEAD, PUT,

DELETE , OPTIONS
Not idempotent: POST


When creating and updating resources…

 PUT if, and only if, you can fully specify the full
content of the resource
 POST if you are sending a command to create or
update one or more subordinates of the specified
resource
 With POST, the server will determine resource URI
Use Location header in the POST response to

specify new resource URI(s) if applicable

HTTPS and SSL certificate validation

5 main HTTP methods

 GET, HEAD, POST, PUT, DELETE
Customization of the data sent in the entity-

body of a PUT or POST request
Customization of HTTP headers

Access to the response status code and

headers
Communicate through HTTP proxies


Transfer and handle compressed data

 Request: Accept-Encoding header
 Response: Encoding header
Cache responses to requests

 Conditional GETs
Common forms of HTTP authentication

 Basic, Digest, and WSSE
Transparently follow HTTP redirects


Hierarchical

 Encode data into path variables on the URI
 http://maps.example.com/Earth/Europe/France/Paris
No hierarchy

 Combine into one path variable, separated by
commas or semicolons
 Use commas when order is important, semicolons
when it doesn’t
 http://maps.example.com/Earth/24.9195,17.821

Algorithmic resources

 Use query variables
 http://www.google.com/search?q=rest

Version your services!

Incorporate the version into the URI

 Set version to the first path variable
 GET /v1/users/34923408
Representations should also be versioned

 Include version information in the representation

Most resources do not change much

Saves client and server processing time and

network bandwidth
Implemented using HTTP headers

 Response headers: Last-Modified and ETag
 Request headers: If-Modified-Since and If-None-
Match

Initial request for resource representation

Request

GET /v1/users/10572 HTTP/1.1
Response

HTTP/1.1 200 OK
Last-Modified: Mon, 13 Apr 2009 18:00:00 GMT
ETag: 1239646841000
Cache-Control: must-revalidate
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Date: Mon, 13 Apr 2009 18:46:00 GMT

Subsequent requests for resource
representation

Request

GET /v1/users/10572 HTTP/1.1
If-Modified-Since: Mon, 13 Apr 2009 18:00:00 GMT
If-None-Match: 1239646841000
Response

HTTP/1.1 304 Not Modified
Date: Mon, 13 Apr 2009 18:47:00 GMT

Microsoft Internet Explorer

 Requires the Expires: -1 header
 Prevents caching in IE
http://support.microsoft.com/kb/234067

Tools

 .NET
▪ Windows Communication Foundation (WCF)
 Java
▪ Spring MVC 3.0
▪ JAX-RS: CXF, Jersey, RESTEasy, RESTlet
Design the REST API

 Don’t just let it happen!
 Seek out resources in your domain

Answer the following questions, in order:

1. What are the URIs? What are the resources of
your application?
2. What is the representational format for the
resources?
3. What methods are supported at each URI?
4. What status codes could be returned for each
method?

Resources can be served in different

representations
 XML, JSON, HTML, etc.
Content negotiation methods

 Headers
▪ Accept or Content-Type
 Query parameter
▪ GET /v1/users/10572?format=json
 URI extension
▪ GET /v1/users/10572.xml

Tools

 Curl
 Apache HttpClient and JUnit
 Fiddler (Windows), HTTP Scoop (OS X), WireShark

Using REST as a RPC-like mechanism

Overusing POST

Putting actions in the URI

Disguising a service as a resource

Maintaining sessions on the server


RESTful Web Services. Leonard Richardson and Sam Ruby.

http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/

http://www.elharo.com/blog/software-development/web-development/2005/12/08/post-

vs-put/
http://www.xml.com/pub/a/2004/12/01/restful-web.html

http://www.xml.com/pub/a/2004/03/17/udell.html

http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

http://www.mozilla.org/projects/netlib/http/http-caching-faq.html

http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html
