1Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
REST (Representational State Transfer)
Roger L. Costello Timothy D. Kehoe
2Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Overview
The Web's simple set of operations, i.e., the Web's API
The Web's fundamental components REST Questions and Answers The REST design pattern (summary) References
3Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
The Web's Simple Set of Operations
(i.e., the Web's API*)
* Application Programming Interface
4Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Web Basics: Retrieving Information using HTTP GET
AmazonWeb Server
GET / HTTP/1.1Host: http://www.amazon.com
http://www.amazon.com
- The user types in at his browser: http://www.amazon.com - The browser software creates an HTTP header (no payload)
- The HTTP header identifies:- The desired action: GET ("get me resource")- The target machine (www.amazon.com)
5Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Web Basics: Updating Information using HTTP POST
AmazonWeb Server
POST / HTTP/1.1Host: http://www.amazon.com
Book: DaVince CodeCredit Card: VisaNumber: 123-45-6789Expiry: 12-04-06
- The user fills in the Web page's form- The browser software creates an HTTP header with a payload
comprised of the form data- The HTTP header identifies:
- The desired action: POST ("here's some update info")- The target machine (amazon.com)
- The payload contains:- The data being POSTed (the form data)
Book: Da Vince CodeCredit Card: VisaNumber: 123-45-6789Expiry: 12-04-06
6Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Terminology: Header and Payload
AmazonWeb Server
POST / HTTP/1.1Host: http://www.amazon.com
Book: DaVince CodeCredit Card: VisaNumber: 123-45-6789Expiry: 12-04-06
Book: Da Vince CodeCredit Card: VisaNumber: 123-45-6789Expiry: 12-04-06
This information (the form data) is called the payload.
This information(the HTTP data)
is called the HTTP header
7Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Web Basics: Simple Set of Operations, via the HTTP API HTTP provides a simple set of operations.
Amazingly, all Web exchanges are done using this simple HTTP API: GET = "give me some info" (Retrieve) POST = "here's some update info" (Update) PUT = "here's some new info" (Create) DELETE = "delete some info" (Delete)
The HTTP API is CRUD (Create, Retrieve, Update, and Delete)
8Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Fundamental Web Components
9Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Web Component: Firewalls(Firewall: "Should I allow POSTing to geocities?")
POST / HTTP/1.1Host: http://www.geocities.com/crafts/woodworking/fred
Item: Woodworking setCredit Card: VisaNumber: 123-45-6789Expiry: 12-04-06
Item: Woodworking setCredit Card: VisaNumber: 123-45-6789Expiry: 12-04-06
F
I
R
E
W
A
L
L
Firewall Rules & PoliciesProhibit all POSTs to the geocities Web site.
The firewall decides whether an HTTP message should pass through
All decisions are based purely upon the HTTP header. The firewall never looks in the payload. This is fundamental!
This message is rejected!
10Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Basic Web Components: Firewalls, Routers, Caches
The Web is comprised of some basic components: Firewalls: these components decide what HTTP messages get out,
and what get in. These components enforce Web security.
Routers: these components decide where to send HTTP messages. These components manage Web scaling.
Caches: these components decide if a saved copy can be used. These components increase Web speed.
All these components base their decisions and actions purely upon information in the HTTP header. "Thou shalt never peek inside the HTTP payload!"
11Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Web Components Operate using only Information found in the
HTTP Header!
HTTP HeaderHTTP Payload
Web Message
Component(firewall, router, cache)
12Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Letter Analogy
Why do Web components base their decisions solely on information in the HTTP header?
My company has a receiving warehouse. All letters and packages go there first, and from there they are distributed.
No one in the receiving warehouse may look inside any letter or package. All decisions about what to do with letters and packages must be made purely by looking at the addressing on the outside. Any attempt to peek inside of letters and packages is a violation of Federal Law (U.S.).
13Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
REST
14Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
What is REST?
" REST " was coined by Roy Fielding in his Ph.D. dissertation [1] to describe a design pattern for implementing networked systems.
[1] http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
15Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Why is it called "Representational State Transfer? "
ResourceClienthttp://www.boeing.com/aircraft/747
Boeing747.html
The Client references a Web resource using a URL. A representation of the resource is returned (in this case as an HTML document).The representation (e.g., Boeing747.html) places the client in a new state. When the client selects a hyperlink in Boeing747.html, it accesses another resource. The new representation places the client application into yet another state. Thus, the client application transfers state with each resource representation.
Fuel requirementsMaintenance schedule...
16Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Representational State Transfer"Representational State Transfer is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through an application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use."
- Roy Fielding
17Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Motivation for REST
The motivation for developing REST was to create a design pattern for how the Web should work, such that it could serve as the guiding framework for the Web standards and designing Web services.
18Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
REST - Not a Standard REST is not a standard
You will not see the W3C putting out a REST specification. You will not see IBM or Microsoft or Sun selling a REST
developer's toolkit. REST is just a design pattern
You can't bottle up a pattern. You can only understand it and design your Web services to it.
REST does prescribe the use of standards: HTTP URL XML/HTML/GIF/JPEG/etc. (Resource Representations) text/xml, text/html, image/gif, image/jpeg, etc. (Resource Types,
MIME Types)
19Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
REST defined
Resources are identified by uniform resource identifiers (URIs)
Resources are manipulated through their representations
Messages are self-descriptive and stateless Multiple representations are accepted or
sent Hypertext is the engine of application state
Representation
Resources are just concepts URIs tell a client that there's a concept
somewhere Clients can then request a specific
representation of the concept from the representations the server makes available
There may be HTML representation (web page), XML representation, JPEG etc
State
State means application/session state Maintained as part of the content
transferred from client to server back to client
Thus any server can potentially continue transaction from the point where it was left off
State is never left in limbo
Transfer of state
Connectors (client, server, cache, resolver, tunnel) are unrelated to sessions
State is maintained by being transferred from clients to servers and back to clients
Nouns and Verbs
Nouns are URIs Each noun (URI) represents a concept Trillions of nouns to represent all the concepts
in all the servers Verbs are actions that are applied to nouns
ReST prescribes four verbs for every noun Get, Put, Post, Delete Or CRUD (Create, Retrieve, Update, Delete)
Four verbs for every noun
GET to retrieve information POST to add new information, showing its
relation to old information PUT to update information DELETE to discard information
Put or Post
Both can be used to Create and Update What you pick may depend on
Does the URI exist already? (Put if it doesnt) Do you create the name (Put) or does the server
(Post) Does repeated invocations keep building up the
resource (Post) or has no effect (Put why?)
26Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Learn by Example
The REST design pattern is best explained with an example.
I will present an example of a company deploying three Web services using the REST design pattern.
27Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Parts Depot Web Services
Parts Depot, Inc has deployed some web services to enable its customers to: get a list of parts get detailed information about a particular part submit a Purchase Order (PO)
28Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
The REST way of Designing the Web Services
W
e
b
S
e
r
v
e
r
HTTP POST URL 3PO(HTML/XML)
HTTP GET request URL 1
HTTP responseURL to submitted PO
PartsList
PartData
PO
HTTP responseResponse(HTML/XML doc)
HTTP responseResponse(HTML/XML doc)
HTTP GET request URL 2
29Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Web Service for Clients to Retrieve a List of Parts
Service: Get a list of parts The web service makes available a URL
to a parts list resource. A client uses this URL to get the parts list: http://www.parts-depot.com/parts Note that how the web service generates the
parts list is completely transparent to the client. This is loose coupling.
30Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
REST Fundamentals Create a resource for every service. Identify each resource using a URL.
31Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Data Returned - Parts List
Note that the parts list has links to get detailed info about each part. This is a key feature of the REST design pattern. The client transfers from one state to the next by examining and choosing from among the alternative URLs in the response document.
32Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
REST Fundamentals The data that a Web service returns
should link to other data. Thus, design your data as a network of information.
Contrast with OO design, which says to encapsulate information.
33Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Web Service for Clients to Retrieve a Particular Part
Service: Get detailed information about a particular part The web service makes available a URL to
each part resource. For example, here's how a client requests a specific part: http://www.parts-depot.com/parts/00345
34Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Data Returned - Part 00345
00345Widget-AThis part is used within the frap assembly
0.1010
Again observe how this data is linked to still more data - the specification for this part may be found by traversing the hyperlink. Each response document allows the client to drill down to get more detailed information.
35Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
QuestionWhat if Parts Depot has a million parts, will there be a million static pages? For example:
http://www.parts-depot/parts/000000http://www.parts-depot/parts/000001...
http://www.parts-depot/parts/999999
36Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
AnswerWe need to distinguish between a logical and a physical entity. The above URLs are logical. They express what resource is desired.
They do not identify a physical object. The advantage of using alogical identifier (URL) is that changes to the underlying implementation of the resource will be transparent to clients (that's loose coupling!).
Quite likely, Parts Depot will store all parts data in a database. Code at the Parts Depot web site will receive each logical URL request, parse it to determine which part is being requested, query the database, and generate the part response document to return to the client.
37Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Answer (cont.)Contrast the above logical URLs with these physical URLs:
http://www.parts-depot/parts/000000.htmlhttp://www.parts-depot/parts/000001.html...
http://www.parts-depot/parts/999999.html
These URLs are clearly pointing to physical (HTML) pages. If there are a million parts it will not be very attractive to have a million static pages. Furthermore, changes to how these parts data is represented will effect all clients that were using the old representation.
38Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
QuestionWhat if I have a complex query?
For example: Show me all parts whose unit cost is under $0.50 and for which the quantity is less than 10
How would you do that with a simple URL?
39Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
AnswerFor complex queries, Parts Depot will provide a service (resource) for a client to retrieve a form that the client then fills in.
When the client hits "Submit" the browser will gather up the clients responses and generate a URL based on the responses.
Thus, oftentimes the client doesn't generate the URL (think about using Amazon - you start by entering the URL to amazon.com; from then on you simply fill in forms, and the URLs are automatically created for you).
40Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
Summary of theREST Design Pattern
41Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
The REST Design Pattern Create a resource for every service. Uniquely identify each resource with a
logical URL. Design your information to link to other
information. That is, the information that a resource returns to a client should link to other information in a network of related information.
42Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
The REST Design Pattern (cont.) All interactions between a client and a web
service are done with simple operations. Most web interactions are done using HTTP and just four operations: retrieve information (HTTP GET) create information (HTTP PUT) update information (HTTP POST) delete information (HTTP DELETE)
43Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
The REST Design Pattern (cont.) Remember that Web components (firewalls,
routers, caches) make their decisions based upon information in the HTTP Header. Consequently, the destination URL must be placed in the HTTP header for Web components to operate effectively. Conversely, it is anti-REST if the HTTP header
just identifies an intermediate destination and the payload identifies the final destination.
44Copyright [2005]. Roger L. Costello, Timothy D. Kehoe. All Rights Reserved.
References Paul Prescod has written several excellent
articles on REST: Second Generation Web Services
http://www.xml.com/pub/a/2002/02/06/rest.html REST and the Real World
http://www.xml.com/pub/a/2002/02/20/rest.html SOAP, REST and Interoperability
http://www.prescod.net/rest/standardization.html Evaluating XML for Protocol Control Data
http://www.prescod.net/xml/envelopes/
Further Reading
Lessons learnt from designing the Red Hat
Enterprise Virtualization API
restful-api-design.readthedocs.org/en/latest
Presentation by Brian Mulloy at Apigee where he
starts with a typical poorly-designed API and
iterate it into a well-behaved RESTful API
blog.apigee.com/detail/restful_api_design
How to Avoid Common REST Mistakes
[Long URL. JGI]
6 Examples [rest.elkstein.org]
The Google Glass API: youtu.be/JpWmGX55a40
Twitter API: dev.twitter.com/docs/api
Flickr API: www.flickr.com/services/api/
Amazon S3: docs.aws.amazon.com/AmazonS3/2006-03-
01/API/APIRest.html
Atom: RFC 4287 and 5023
Tesla Model S: docs.timdorr.apiary.io/
Top Related