restful web serviceskti.tugraz.at/staff/denis/courses/mmis2/material/slides_ws_main.pdf · restful...
TRANSCRIPT
RESTful Web ServicesMMIS 2 VU SS 2011 - 707.025
Denis Helic
KMI, TU Graz
April 14, 2011
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 1 / 69
Web as a database
The Web we use is full of data
Book information, opinions, prices, arrival times, blogs, tags, tweets,etc.
The data is organized around a simple data model: node-link model
Each node is a data item that has a unique address and arepresentation
Representation formats are e.g. HTML, PDF,... for humans, or e.gXML, JSON for programs
Nodes can be interlinked using their unique addresses
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 2 / 69
Web as a platform for distributed systems
The Web is full of services that allow humans and programs to usethe Web data
Service also have unique addresses
They use a particular representation for data exchange, e.g. XML,SOAP, WSDL
Services follow a particular architecture that defines how services areused
Programmers combine a number of services to achieve a desiredfunctionality and create a distributed system, e.g. mashups
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 3 / 69
Types of services
What is the Google search engine?
It is a service for querying a massive database (Web search index)
What is a given Web application?
It is a service offering (remotely) a specific functionality
What is a Web site?
It is a service offering specific human consumable information
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 4 / 69
Types of services
All of these services are for users
However, we are interested in services for programmers
Such services provide an API
Programmers use the API, unique addresses, representations ofservices
Programmers follow the arch. style to integrate and combine servicesto achieve a desired functionality
We will call this part of the Web: the programmable Web
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 5 / 69
Kind of Things on the Programmable Web
There are numerous approaches to web services in all areas
The programmable Web is based on HTTP for data transport and inmost cases XML for data representation
However, some services serve HTML, JSON, plain text, binary data,etc.
Also, other things such as addressability or APIs are different
We need a classification!
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 6 / 69
Classification based on architectural design
Which operation should a service execute?
This is method information
What data should be manipulated?
This is scoping information
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 7 / 69
Method information
Question: how the client conveys its intention to the server?
How does a server know a certain request is a request to retrievesome data?
Instead of a request to delete the same data?
Why should the server do this instead of doing that
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 8 / 69
Method information
First alternative
Convey method information by putting it in the HTTP method
GET, DELETE, PUT, POST
Semantics is clear
It is standardized
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 9 / 69
Method information
Second alternative: e.g. Flickr services
http://www.flickr.com/services/rest?method=flickr.photos.
search&tags=penguin
http://www.flickr.com/services/rest?method=flickr.photos.
addTags&...
http://www.flickr.com/services/rest?method=flickr.photos.
deleteComment&...
Method information is in a query variable, all methods use GET(although some change the data)
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 10 / 69
Method information
Third alternative: SOAP and WSDL
Method information is in the SOAP message encoded as defined by aWSDL
wsdl_uri = ’http://api.google.com/GoogleSearch.wsdl’
driver = SOAP.create_rpc_driver(wsdl_uri)
result_set = driver.doGoogleSearch(...)
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 11 / 69
Method information
POST search/beta2 HTTP/1.1
...
<soap:Envelope>
<soap:Body>
<gs:doGoogleSearch>
<q>REST</q>
</gs:doGoogleSearch>
</soap:Body>
</soap:Envelope>
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 12 / 69
Method information
<operation name="doGoogleSearch">
<input message="typens:doGoogleSearch" />
<output message="typens:doGoogleSearchResponse" />
</operation>
Method information defined in WSDL and used in SOAP and viaSOAP-framework in the code
HTTP method is always POST
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 13 / 69
Scoping information
Question: How the client tells the server on which data to operate?
E.g. the server knows that the client wants to delete some data, butwhich data is it?
Why should server operate on this data instead of that data?
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 14 / 69
Scoping information
First alternative: as query variables in URL
http://www.google.com/search?q=REST
Scoping information is q=REST
Method information is in GET
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 15 / 69
Scoping information
Yet another example Flickr
Most of the query variables are scoping information
tags=penguin
Recollect that Flickr also includes method information in queryvariables
Thus, URL contains a method and a number of arguments for thatmethod
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 16 / 69
Scoping information
Second alternative: scoping information in the body of a SOAPmessage
POST search/beta2 HTTP/1.1
...
<soap:Envelope>
<soap:Body>
<gs:doGoogleSearch>
<q>REST</q>
</gs:doGoogleSearch>
</soap:Body>
</soap:Envelope>
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 17 / 69
Competing Architectures
RESTful, Resource-Oriented Architectures
RPC-Style Architectures
REST-RPC Hybrid Architectures
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 18 / 69
RPC-Style Architectures
RPC - Remote Procedure Call
An RPC style service receives an envelope full of data from the client
The service answers with a similar envelope again full of data to theclient
Both method and scoping information are inside of the envelope
HTTP methods typically POST but sometimes also GET
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 19 / 69
RPC-Style Architectures
The best example of the envelope format is SOAP
There exist other envelope formats like XML-RPC
Every RPC-style service defines a completely new vocabulary
E.g. the way how method information and scoping information arerepresented
You need another language to define the representation: e.g. WSDL
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 20 / 69
Problems of SOAP/WSDL
RPC implies an API
APIs tend to enforce tight coupling of modules and systems
We use declarative XML to describe APIs
This introduces processing overhead
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 21 / 69
Problems of SOAP/WSDL
APIs and there definitions in some language e.g. WSDL introducenew vocabulary and hence a new addressability schema
This is a big problem for service integration, in particular forautomatic integration
Each service needs to understands what all other services provide andhow to address the functionality
But where are URLs, links, representations?
All the nice Web elements that made it successful!
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 22 / 69
RESTful, Resource Oriented Architectures
RESTful services look like the Web
Method information goes into into the HTTP method
Scoping information goes into the URL
If the method information is not in HTTP method - the service is notRESTful
If the scoping information is not in the URL - the service is notRESTful
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 23 / 69
Some examples of RESTful services
Services that expose Atom Publishing Protocol, such as GData
Amazon’s Simple Storage Service S3
Most of Yahoo!’s web services
Static web sites
Many web applications, especially read-only such as search engines
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 24 / 69
Clients for RESTful services
In principle clients are simple HTTP clients
When you program a client you need an HTTP library
In most cases you will need an XML library to parse the response
Programatically, clients are in a typical case extremely simple
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 25 / 69
Client for a RESTful service - Example
Example using Simple Storage Service - S3
S3 allows you to store any data you like using different structures
S3 is based on two concepts: buckets and objects
A bucket is analogous to the filesystem
An object is analogous to a file
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 26 / 69
Client for a RESTful service - Example
S3 service exposes three resources that you can manipulate
The list of your buckets https://s3.amazonaws.com/
A particular bucket https://s3.amazonaws.com/name-of-bucket/
A particular object inside a buckethttps://s3.amazonaws.com/name-of-bucket/name-of-object
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 27 / 69
Client for a RESTful service - Example
Every resource exposes the same interface and works in the same way
To get an object’s value you send a GET request to the object’s URL
To get only object’s metadata you send a HEAD request to the sameURL
To add an object to a bucket you send a PUT request to a URL thathas the bucket name and the object’s name
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 28 / 69
Client for a RESTful service - Example
HOST = ’https://s3.amazonaws.com/’
doc = REXML::Document.new(open(HOST).read)
REXML::XPathj.each(doc, "//Bucket/Name") do |e|
buckets << Bucket.new(e.text) if e.text
end
return buckets
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 29 / 69
Client for a RESTful service - Example
<Buckets>
<Bucket>
<Name>crummy.com</Name>
<CreationDate>...</CreationDate>
</Bucket>
...
</Buckets>
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 30 / 69
Resource Oriented Architectures
4 defining features of ROA
Addressability: the scoping information is kept in the URL
Uniform interface: the method information is kept in the HTTPmethod
Statelessness: every HTTP request is isolated from other requests
Connectedness: you link resources into the Web of resources
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 31 / 69
Addressability
Resources are exposed through URLs - an application exposes anumber of URLs
When you have URLs you bookmark, cache responses, chain URLs, ...
Many Web applications do not work this way, i.e. they are notaddressable, e.g. GMail
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 32 / 69
Uniform interface
Standardized HTTP methods: CRUD operations
Two principles
Safety: GET only reads data
Idempotence: the same operation has the same effect wheter youapply it once or multiple times
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 33 / 69
Statelessness
Every request contains all necessary information
There is no state managed on the server side
In fact, there are two kinds of state
You should distinguish between the application state and resourcestate
Application state lives on the client
Resource state lives on the server
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 34 / 69
Statelessness
When you use a search engine your current query and your currentpage belongs to application state
They are different for every client
Resource state is same for every client, i.e. search index
A crawler can update the search index
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 35 / 69
Links and connectedness
Representations of resources, i.e. HTML or XML might have links toother resources
Axiom for REST services: Hypermedia as the engine of applicationstate
The current application state is not stored on the server as a resourcestate
It is tracked by the client as an application state and created by thepath that client takes through the Web
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 36 / 69
Links and connectedness
For example http://www.google.com/search?q=jellyfish
The first page is the starting application state
You have links to other application states
Obvious for the human Web
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 37 / 69
Links and connectedness
<Buckets>
<Bucket>
<Name>crummy.com</Name>
<URL>https://s3.amazonaws.com/crummy.com</URL>
<CreationDate>...</CreationDate>
</Bucket>
...
</Buckets>
Following the link in the URL element takes the client to a newapplication state
Use links, links, and then use more links, ...
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 38 / 69
Designing RESTful services
Figure out data set
Split the data set into resources
Then, for each resource
Name the resources with URLs
Expose a subset of the uniform interface
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 39 / 69
Designing RESTful services
Design representations accepted from the client
Design representations served to the client
Integrate this resource into other resources using links
Consider possible application states
Consider possible error states
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 40 / 69
Example
Application similar google maps: maps of cities, streets, planets,...
Data set: Maps, points, cities, planets, ....
Resources: list of resources, individual resources, results of algorithmsapplied to the data set
Example resources: the list of planets, Mars, Earth, San Francisco,Inffeldgasse, ...
An algorithmic resource: a list of places that match certain criteria -all cities with more than 1 million of people
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 41 / 69
Example
Name the resources: create meaningful URLs
http://maps.example.com/Earth
http://maps.example.com/Earth/France/Paris
http://maps.example.com/Earth/Austria/Cities
http://maps.example.com/Earth/Germany/Cities?pop=1000000
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 42 / 69
Example
Design representations
A representation talks about resource state
A representation links to other (application and resource) states
http://maps.example.com/Earth/Austria →http://maps.example.com/Earth/Austria/Cities
http://maps.example.com/Earth/Austria/Cities →http://maps.example.com/Earth/Austria/Vienna
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 43 / 69
Read/Write RESTful services
User accounts should be resources
To access these resources you need to use HTTP authentication
https://maps.example.com/user/dhelic
Connect with the previous resources: e.g. custom places on a map
https://maps.example.com/user/dhelic/Earth/Graz/Inffeldgasse/office
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 44 / 69
RESTful frameworks
Ruby on Rails with a plugin
Django in Python
Restlet in Java (http://www.restlet.org/)
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 45 / 69
Restlet example
public Restlet createRoot(){
Router router = new Router(getContext());
router.attach("/users/{username}",
UserResource.class);
router.attach("users/{username}/bookmarks",
BookmarksResource.class);
router.attach("users/{username}/bookmark/{URL}",
BookmarkResource.class);
}
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 46 / 69
Restlet example
public UserResource(Context context, Request request,
Response response){
super(context, request, response);
username_ = (String) request.getAttribute().
get("username");
...
getVariants().add(new Variant(MediaType.TEXT_PLAIN));
}
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 47 / 69
Restlet example
public Representation getRepresentation(Variant variant){
...
if(variant.getMediaType().equals(MediaType.
TEXT_PLAIN)){
result = "-----User details-------";
...
}
return result;
}
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 48 / 69
REST Web service: Example
To create a REST Web service the following steps should beaccomplished
Define URLs
Define XML vocabulary
Define which methods are available at each URL
Define HTTP status codes
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 49 / 69
REST Web service: Example
Defining URLs
Recollect the clean URLs that we have discussed before
Course with ID 1: http://localhost:3000/courses/1
Course with ID 2: http://localhost:3000/courses/2
All courses: http://localhost:3000/courses/
Note that URLs are regular, i.e., we can automatically construct them
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 50 / 69
REST Web service: Example
Defining XML formats
Single course
<?xml version="1.0" encoding="UTF-8"?>
<course>
<title>MMIS2</title>
<url>http://coronet.iicm.edu/lectures/mmis2</url>
<id type="integer">1</id>
<description>Advanced course on multimedia
information systems</description>
</course>
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 51 / 69
REST Web service: Example
All courses (collection)
<?xml version="1.0" encoding="UTF-8"?>
<courses>
<course>
<title>MMIS2</title>
<url>http://coronet.iicm.edu/lectures/mmis2</url>
<id type="integer">1</id>
<description>Advanced course on multimedia
information systems</description>
</course>
<course>...</course>
</courses>
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 52 / 69
REST Web service: Example
Defining methods
http://localhost:3000/courses/ GET and POST
GET retrives the list, POST adds another course to the list
http://localhost:3000/courses/1 GET, PUT, DELETE
PUT updates the course
Additionally, send OPTIONS at each URL to see what is available
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 53 / 69
REST Web service: Example
Defining HTTP status codes
GET: HTTP/1.1 200 OK
POST: HTTP/1.1 201 Created
PUT, DELETE: HTTP/1.1 204 No Content
Error code: HTTP/1.1 500 Internal Server Error
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 54 / 69
REST Web service: Example
We need a Web server that can dispatch URLs and HTTP methodsto appropriate code
Within that code we manipulate resources using their XMLrepresentations
With Rails we can also dispatch URLs easy
Recollect that Rails dispatch to a class and a method within that class
We need to dispatch to a class and according to the HTTP method
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 55 / 69
REST Web service: Example
There is a Rails plugin that does exactly that
RESTful Rails controllerhttp://rubyforge.org/projects/restful-rails/
class CourseController < ApplicationController
include RestController::Base
...
end
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 56 / 69
REST Web service: Example
The plugin allows you to introduce resources and within resourceshandle HTTP methods
resource :collection do |r|
conditions << @courses = Course.find_all
r.post do
...
end
end
GET method is automatically handled and connected with appropriateXML-based view
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 57 / 69
REST Web service: Example
collection.rxml in views directory
xml.instruct!
xml.courses do
xml.title ’Courses’
@courses.each do |course|
xml.course do
xml.id course.id
xml.title course.title
xml.url course.url
xml.description course.description
...
end
end
end
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 58 / 69
REST Web service: Example
Handling POST to the collection (adding a course)
r.post do
@course = Course.new params[:course]
if @course.save
render_post_success :action => ’by_id’,
:id => @course
end
end
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 59 / 69
REST Web service: Example
Handling of single courses (introduce a new rule by id)
resource :by_id do |r|
conditions << @course = Course.find(params[:id])
r.put do
@course.attributes = params[:course]
if @course.save
render_put_success
end
end
end
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 60 / 69
REST Web service: Example
Deleting a resource
...
r.delete do
if @course.destroy
render_delete_success :id => nil
end
end
...
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 61 / 69
REST Web service: Example
GET XML view
xml.instruct!
@course.to_xml
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 62 / 69
REST Web service: Example
Demo: http://coronet.iicm.edu/mmis2/examples/ws/rest/
rest_courses.zip
curl http://localhost:3000/courses
curl http://localhost:3000/courses/1
curl -i -X POST -d ’<course><title>
Web Information Systems</title></course>’
http://localhost:3000/courses
curl -i -X PUT -H ’Content-Type: application/xml’ -d ’<course>
<title>Web Information Systems</title>
<description>Very advanced course</description>
</course>’
http://localhost:3000/courses/4
curl -i -X DELETE http://localhost:3000/courses/4
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 63 / 69
REST-RPC Hybrid Architectures (1)
Services somewhere between RESTful and RPC services
http://www.flickr.com/services/rest?method=flickr.photos.
search&tags=penguin
Both method and scoping information is in URL
HTTP is used as an envelope format
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 64 / 69
REST-RPC Hybrid Architectures (2)
GET services/rest?method=flickr.photos.search&
tags=penguin HTTP/1.1
Host: www.flickr.com
Another prominent example of this style is del.icio.us
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 65 / 69
Programmable Web
http://www.programmableweb.com/
http://www.programmableweb.com/tag/ajax
http://www.2lingual.com/
http://www.ajaxonomy.com/deliciousspy/
http://flickr.mathewvp.com/
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 66 / 69
Programmable Web
http://labs.umaniac.com/projects/twitter_user_trends/demo.php
http://goosh.org/
http://www.programmableweb.com/apis
http://www.programmableweb.com/apis/directory/1?protocol=REST
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 67 / 69
Further Readings
What is Service-Oriented Architecture?http://webservices.xml.com/pub/a/ws/2003/09/30/soa.html
A Web Services Primerhttp://webservices.xml.com/pub/a/ws/2001/04/04/
webservices/index.html
Top Ten FAQs for Web Serviceshttp://webservices.xml.com/pub/a/ws/2002/02/12/
webservicefaqs.html?page=1
Service-Oriented Architecture and Web Services: Concepts,Technologies, and Toolshttp://java.sun.com/developer/technicalArticles/
WebServices/soa2/index.html
Articles on http://webservices.xml.com/ from O’Reilly
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 68 / 69
Further Readings
REST definition (PhD Thesis of Roy Fielding)http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
http://www.ics.uci.edu/~fielding/pubs/dissertation/
rest_arch_style.htm
The Restful Web: Column on xml.comhttp://xml.com/pub/at/34
Putting REST on Railshttp://www.xml.com/pub/a/2006/04/19/rest-on-rails.html
REST vs SOAP: Second Generation Web Serviceshttp://webservices.xml.com/pub/a/ws/2002/02/06/rest.html
Denis Helic (KMI, TU Graz) RESTful Web Services April 14, 2011 69 / 69