Some REST Design Patterns (and Anti-Patterns) - SOA Symposium 2009

Some REST Design Patterns
(and Anti-Patterns)

Cesare Pautasso
Faculty of Informatics
University of Lugano, Switzerland

c.pautasso@ieee.org
http://www.pautasso.info

Abstract
 The REST architectural style is simple to define, but
understanding how to apply it to design concrete
REST services in support of SOA can be more
complex. The goal of this talk is to present the main
design elements of a RESTful architecture and
introduce a pattern-based design methodology for
REST services.
 A selection of REST-inspired SOA design patterns
taken from the upcoming "SOA with REST" book will
be explained and further discussed to share useful
solutions to recurring design problems and to also
the foundational building blocks that comprise the
REST framework from a patterns perspective.
 We will conclude by introducing some common SOA
anti-patterns particularly relevant to the design of
REST services in order to point out that not all
current Web services that claim to be RESTful are
indeed truly so.
©2009 - Cesare Pautasso 2

Acknowledgements
 The following distinguished individuals have
contributed to the the patterns and reviewed some of
the material presented in this talk:
 Raj Balasubramanian
 Benjamin Carlyle
 Thomas Erl
 Stefan Tilkov
 Erik Wilde
 Herbjorn Wilhelmsen
 Jim Webber

 And all the participants, sheperds and sheeps
of the SOA Patterns Workshop

About Cesare Pautasso
 Assistant Professor at the Faculty of Informatics,
University of Lugano, Switzerland (since Sept 2007)
Research Projects:
 SOSOA – Self Organizing Service Oriented Architectures
-
 CLAVOS – Continuous Lifelong Analysis and Verification of
Open Services
 BPEL for REST
 Researcher at IBM Zurich Research Lab (2007)
 Post Doc at ETH Zürich
-
 Software:
JOpera: Process Support for more than Web services
http://www.jopera.org/
 Ph.D. at ETH Zürich, Switzerland (2004)

 Representations:
http://www.pautasso.info/ (Web)
http://twitter.com/pautasso/ (Twitter Feed)


REST Patterns - Outline
• Design Methodology
• Simple Doodle Service Example & Demo
• SOA Design Patterns
• Entity Endpoint
• Uniform Contract
• Endpoint Redirection
• Content Negotiation
• Idempotent Capability
• AntiPatterns
• Tunneling everything through GET
• Tunneling everything through POST

Design Methodology for REST
1. Identify resources to be exposed as
services (e.g., yearly risk report, book

DELETE
catalog, purchase order, open bugs,

POST
polls and votes)

GET

PUT
2. Model relationships (e.g., containment,
reference, state transitions) between /loan    
resources with hyperlinks that can be
followed to get more details (or perform /balance    
state transitions) /client    
3. Define “nice” URIs to address the
resources /book    
4. Understand what it means to do a GET,
POST, PUT, DELETE for each resource /order  ?  
(and whether it is allowed or not)
5. Design and document resource
representations /soap    
6. Implement and deploy on Web server
7. Test with a Web browser

Design Space
M Representations (Variable)

4 Methods (Fixed)

le)
(Variab
urces
N Reso


Simple Doodle API Example Design
1. Resources:

DELETE
polls and votes

POST
2. Containment Relationship:

GET
PUT
poll /poll    
{id1} /poll/{id}    
vote /poll/{id}/vote    
{id4} /poll/{id}/vote/{id}    ?

{id5} 3. URIs embed IDs of “child”
instance resources
4. POST on the container is used to
{id2} create child resources
5. PUT/DELETE for updating and
{id3} removing child resources


Simple Doodle API Example
1. Creating a poll
(transfer the state of a new poll on the Doodle service)
/poll
/poll/090331x
/poll/090331x/vote

POST /poll GET /poll/090331x
<options>A,B,C</options>
200 OK
201 Created <options>A,B,C</options>
Location: /poll/090331x <votes href=“/vote”/>

2. Reading a poll
(transfer the state of the poll from the Doodle service)

 Participating in a poll by creating a new vote sub resource
-
/poll
/poll/090331x
/poll/090331x/vote
/poll/090331x/vote/1

POST /poll/090331x/vote GET /poll/090331x
<name>C. Pautasso</name>
<choice>B</choice> 200 OK
201 Created <votes><vote id=“1”>
Location: <name>C. Pautasso</name>
/poll/090331x/vote/1 <choice>B</choice>
</vote></votes>


 Existing votes can be updated (access control headers not shown)
/poll
/poll/090331x
/poll/090331x/vote

PUT /poll/090331x/vote/1 GET /poll/090331x
<choice>C</choice> 200 OK
200 OK <votes><vote id=“/1”>
<choice>C</choice>
</vote></votes>


 Polls can be deleted once a decision has been made
/poll
/poll/090331x
/poll/090331x/vote

DELETE /poll/090331x GET /poll/090331x

200 OK 404 Not Found


Design Patterns
Content
Negotiation
4 Methods (Fixed)

le)
(Variab
Entity Uniform
Endpoint Contract
urces
N Reso

Endpoint
Idempotent
Redirect
Capability

Pattern: Uniform Contract
calculateRate()
Provider US
retrieveTaxRate()
Provider CH
Consumer
figureOutRateForTax()
Provider IT

 How can consumers take advantage of multiple evolving
service endpoints?
 Problem: Accessing similar services requires consumers to
access capabilities expressed in service specific contracts.
-
The consumer needs to be kept up to date with respect to
many evolving individual contracts.


Pattern: Uniform Contract
GET www.irs.gov/rate
Provider US
GET www.admin.ch/tax/rate
Provider CH
Consumer
GET www.tesoro.it/tasse/iva
Provider IT

 Solution: Standardize a uniform contract across alternative
service endpoints that is abstracted from the specific
capabilities of individual services.
 Benefits: Service Abstraction, Loose Coupling, Reusability,
Discoverability, Composability.


Example Uniform Contract

CRUD REST
Create a
CREATE POST sub resource
Retrieve the current
READ GET state of the resource
Initialize or update the
UPDATE PUT state of a resource
at the given URI

Clear a resource,
DELETE DELETE after the URI is no
longer valid


POST vs. GET
 GET is a read-only operation.
It can be repeated without
affecting the state of the
resource (idempotent) and
can be cached.
Note: this does not mean that
the same representation will
be returned every time. Web browsers warn
 POST is a read-write you when refreshing
operation and may change a page generated
the state of the resource and with POST
provoke side effects on the
server.


POST vs. PUT
What is the right way of creating resources (initialize their state)?
PUT /resource/{id}
201 Created
Problem: How to ensure resource {id} is unique?
(Resources can be created by multiple clients concurrently)
Solution 1: let the client choose a unique id (e.g., GUID)

POST /resource
301 Moved Permanently
Location: /resource/{id}
Solution 2: let the server compute the unique id
Problem: Duplicate instances may be created if requests are
repeated due to unreliable communication


Pattern: Endpoint Redirection
Stale Reference

Consumer Service Endpoint
Redirect

Consumer Old Endpoint New Endpoint

 How can consumers of a service endpoint adapt when service
inventories are restructured?
 Problem: Service inventories may change over time for
business or technical reasons. It may not be possible to
replace all references to old endpoints simultaneously.
 Solution: Automatically refer service consumers that access
the stale endpoint identifier to the current identifier.

Endpoint Redirection with HTTP
/old /new
 HTTP natively supports
the Endpoint redirection
GET /old pattern using a
combination of 3xx
301 Moved Permanently
Location: /new
status codes and
standard headers:
 301 Moved Permanently
 307 Temporary Redirect
GET /new
 Location: /newURI
200 OK

 Tip: Redirection responses can be chained.
 Warning: do not create redirection loops!

Design Patterns
Content
Negotiation
4 Methods (Fixed)

le)
(Variab
Entity Uniform
Endpoint Contract
urces
N Reso

Endpoint
Idempotent
Redirect
Capability

Pattern: Entity Endpoint
Provider
Consumer Endpoint
A B C
X Y Z
X
Business Entities
Z

 How can entities be positioned as reusable enterprise resources?
 Problem: A service with a single endpoint is too coarse-grained when its
capabilities need to be invoked on its data entities. A consumer needs to
work with two identifiers: a global one for the service and a local one for
the entity managed by the service. Entity identifiers cannot be reused and
shared among multiple services


Pattern: Entity Endpoint

Consumer Provider Entity Endpoints
X Y Z A B C

 Solution: expose each entitity as individual lightweight
endpoints of the service they reside in
 Benefits: Global addressability of service entities


URI - Uniform Resource Identifier

 Internet Standard for resource naming and identification
(originally from 1994, revised until 2005)
 Examples:
http://tools.ietf.org/html/rfc3986

URI Scheme Authority Path
https://www.google.ch/search?q=rest&start=10#1

Query Fragment
 REST does not advocate the use of “nice” URIs
 In most HTTP stacks URIs cannot have arbitrary length (4Kb)


What is a “nice” URI?
A RESTful service is much more than just a set of nice URIs

http://map.search.ch/lugano

http://maps.google.com/lugano

http://maps.google.com/maps?f=q&hl=en&q=lugano,
+switzerland&layer=&ie=UTF8&z=12&om=1&iwloc=addr


URI Design Guidelines
 Prefer Nouns to Verbs GET /book?isbn=24&action=delete
 Keep your URIs short DELETE /book/24
 If possible follow a
“positional” parameter-  Note: REST URIs are opaque
passing scheme for identifiers that are meant to
algorithmic resource query be discovered by following
strings (instead of the hyperlinks and not
key=value&p=v encoding) constructed by the client

 Some use URI postfixes to  This may break the
specify the content type abstraction

 Do not change URIs  Warning: URI Templates
 Use redirection if you really introduce coupling between
need to change them client and server


Pattern: Content Negotiation

Consumer
?
Service
New Consumer

 How can services support different consumers without
changing their contract?
 Problem: Service consumers may change their requirements in
a way that is not backwards compatible. A service may have to
support both old and new consumers without having to
introduce a specific capability for each kind of consumer.


Pattern: Content Negotiation

Consumer

Service
New Consumer

 Solution: specific content and data representation formats to
be accepted or returned by a service capability is negotiated at
runtime as part of its invocation. The service contract refers to
multiple standardized “media types”.
 Benefits: Loose Coupling, Increased Interoperability, Increased
Organizational Agility


Content Negotiation in HTTP
Negotiating the message format does not require to send more
messages (the added flexibility comes for free)
GET /resource
Accept: text/html, application/xml,
application/json
1. The client lists the set of understood formats (MIME types)

200 OK
Content-Type: application/json
2. The server chooses the most appropriate one for the reply
(status 406 if none can be found)


Advanced Content Negotiation
Quality factors allow the client to indicate the relative
degree of preference for each representation (or
media-range).
Media/Type; q=X
If a media type has a quality value q=0, then content with
this parameter is not acceptable for the client.
Accept: text/html, text/*; q=0.1
The client prefers to receive HTML (but any other text format
will do with lower priority)
Accept: application/xhtml+xml; q=0.9,
text/html; q=0.5, text/plain; q=0.1
The client prefers to receive XHTML, or HTML if this is not
available and will use Plain Text as a fall back


Forced Content Negotiation
The generic URI supports content negotiation
GET /resource
Accept: text/html, application/xml,
application/json
The specific URI points to a specific representation format using
the postfix (extension)
GET /resource.html
GET /resource.xml
GET /resource.json
Warning: This is a conventional practice, not a standard.
What happens if the resource cannot be represented in the
requested format?


Multi-Dimensional Negotiation
Content Negotiation is very flexible and can be
performed based on different dimensions
(each with a specific pair of HTTP headers).

Request Header Example Values Response Header
Accept: application/xml, Content-Type:
application/json
Accept-Language: en, fr, de, es Content-Language:

Accept-Charset: iso-8859-5, Charset parameter fo the
unicode-1-1 Content-Type header
Accept-Encoding: compress, Content-Encoding:
gzip


Pattern: Idempotent Capability
Client Service Client Service

Timeout Timeout
!!!

 How can a service consumer recover from lost messages after network
disruption or server failure within a service cluster?
 Problem: Service oriented architectures are distributed systems. Failures
(such as the loss of messages) may occur during service capability
invocation. A lost request should be retried, but a lost response may cause
unintended side-effects if retried automatically.


Client ESB ESB Service

Timeout

 Solution: use an ESB, with support for reliable
messaging.
 Problem: do we always need this? Are there
some messages more critical than others?

Client Service

 Simpler Solution: if possible use idempotent
service capabilities, whereby services provide
a guarantee that capability invocations are
safe to repeat in the case of failures that could
lead to a response message being lost

Idempotent vs. Unsafe
 Idempotent requests can be  Unsafe requests modify the state of
processed multiple times the server and cannot be repeated
without side-effects without additional (unwanted) effects:
GET /book Withdraw(200$) //unsafe
PUT /order/x Deposit(200$) //unsafe
DELETE /order/y  Unsafe requests require special
 If something goes wrong handling in case of exceptional
(server down, server situations (e.g., state reconciliation)
internal error), the request POST /order/x/payment
can be simply replayed until  In some cases the API can be
the server is back up again redesigned to use idempotent
 Safe requests are operations:
idempotent requests which B = GetBalance() //safe
do not modify the state of
B = B + 200$ //local
the server (can be cached)
SetBalance(B) //idempotent
GET /book


Dealing with Concurrency
/balance
 Breaking down the API into a
set of idempotent requests
GET /balance helps to deal with temporary
failures.
200 OK  But what about if another
ETag: 26 client concurrently modifies
PUT /balance the state of the resource we
ETag: 26 are about to update?
 Do we need to create an
200 OK explicit /balance/lock
ETag: 27 resource? (Pessimistic
Locking)
 Or is there an optimistic
solution?

Dealing with Concurrency
/balance

GET /balance

200 OK PUT /balance
ETag: 26 ETag: 26

PUT /balance 200 OK
ETag: 26 ETag: 27

409 Conflict

The 409 status code can be used to inform a client that his
request would render the state of the resource inconsistent

Antipatterns - REST vs. HTTP

REST HTTP

“RPC”
RESTful HTTP

Antipatterns – HTTP as a tunnel
 Tunnel through one HTTP Method
GET /api?method=addCustomer&name=Pautasso
GET /api?method=deleteCustomer&id=42
GET /api?method=getCustomerName&id=42
GET /api?method=findCustomers&name=Pautasso*

 Everything through GET
• Advantage: Easy to test from a Browser address bar
(the “action” is represented in the resource URI)
• Problem: GET should only be used for read-only
(= idempotent and safe) requests.
What happens if you bookmark one of those links?
• Limitation: Requests can only send up to approx. 4KB of data
(414 Request-URI Too Long)

Antipatterns – HTTP as a tunnel
 Tunnel through one HTTP Method
 Everything through POST
• Advantage: Can upload/download an arbitrary amount of data
(this is what SOAP or XML-RPC do)
• Problem: POST is not idempotent and is unsafe (cannot cache
and should only be used for “dangerous” requests)

POST /service/endpoint
Is t h
is a
<soap:Envelope> reso
<soap:Body> urce
<findCustomers> ?
<name>Pautasso*</name>
</findCustomers>
</soap:Body>
</soap:Envelope>

REST Design Patterns
1. Uniform Contract
2. Entity Endpoint
3. Entity Linking*
4. Content Negotiation
5. Distributed Response Caching*
6. Endpoint Redirection
7. Idempotent Capability
8. Message-based State Deferral*
9. Message-based Logic Deferral*
10.Consumer-Processed Composition*
*Not Included in this talk

References
 R. Fielding, Architectural Styles and the Design of Network-
based Software Architectures, PhD Thesis,
University of California, Irvine, 2000
 C. Pautasso, O. Zimmermann, F. Leymann, RESTful Web
Services vs. Big Web Services: Making the Right Architectural
Decision, Proc. of the 17th International World Wide Web
Conference (WWW2008), Bejing, China, April 2008
 C. Pautasso, BPEL for REST, Proc. of the 7th International
Conference on Business Process Management
(BPM 2008), Milano, Italy, September 2008
 C. Pautasso, Composing RESTful Services with JOpera,
In: Proc. of the International Conference on Software
Composition (SC2009), July 2009, Zurich, Switzerland.
© 43

Conclusion

Raj Balasubramanian,
 Applying the SOA composition principle to
Benjamin Carlyle,
Thomas Erl,
REST gives interesting results Pautasso,
Cesare
 Thanks to hyperlinks, REST SOA with a new
brings REST,
(more dynamic and loosely coupled)
Prentice Hall,
twist to SOA composition to appear in 2010
 Composing RESTful services helps to build
mashups, but is different
 A RESTful API is the perfect abstraction for
publishing the state of a workflow


Some REST Design Patterns (and Anti-Patterns) - SOA Symposium 2009

Recommended

More Related Content

What's hot (20)

Similar to Some REST Design Patterns (and Anti-Patterns) - SOA Symposium 2009 (20)

More from Cesare Pautasso (20)

Recently uploaded (20)

Some REST Design Patterns (and Anti-Patterns) - SOA Symposium 2009