RESTful Web Serviceskti.tugraz.at/staff/denis/courses/mmis2/material/slides_ws_main.pdf · RESTful...

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


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


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


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


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!


Classification based on architectural design

Which operation should a service execute?

This is method information

What data should be manipulated?

This is scoping information


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


Method information

First alternative

Convey method information by putting it in the HTTP method

GET, DELETE, PUT, POST

Semantics is clear

It is standardized


Method information

Second alternative: e.g. Flickr services

http://www.flickr.com/services/rest?method=flickr.photos.

search&tags=penguin


addTags&...


deleteComment&...

Method information is in a query variable, all methods use GET(although some change the data)


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.addTags&...

http://www.flickr.com/services/rest?method=flickr.photos.deleteComment&...

http://www.flickr.com/services/rest?method=flickr.photos.deleteComment&...

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(...)


Method information

POST search/beta2 HTTP/1.1

...

<soap:Envelope>

<soap:Body>

<gs:doGoogleSearch>

<q>REST</q>

</gs:doGoogleSearch>

</soap:Body>

</soap:Envelope>


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


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?


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


http://www.google.com/search?q=REST

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


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>


Competing Architectures

RESTful, Resource-Oriented Architectures

RPC-Style Architectures

REST-RPC Hybrid 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



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


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


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!


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


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


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


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



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



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



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



<Buckets>

<Bucket>

<Name>crummy.com</Name>

<CreationDate>...</CreationDate>

</Bucket>

...

</Buckets>


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


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


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


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


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


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



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


http://www.google.com/search?q=jellyfish


<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, ...


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


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


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


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


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


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


RESTful frameworks

Ruby on Rails with a plugin

Django in Python

Restlet in Java (http://www.restlet.org/)


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);

}


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));

}


Restlet example

public Representation getRepresentation(Variant variant){

...

if(variant.getMediaType().equals(MediaType.

TEXT_PLAIN)){

result = "-----User details-------";

...

}

return result;

}


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



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


http://localhost:3000/courses/1


http://localhost:3000/courses/


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>



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>



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


http://localhost:3000/courses/



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



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



There is a Rails plugin that does exactly that

RESTful Rails controllerhttp://rubyforge.org/projects/restful-rails/

class CourseController < ApplicationController

include RestController::Base

...

end


http://rubyforge.org/projects/restful-rails/


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



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



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



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



Deleting a resource

...

r.delete do

if @course.destroy

render_delete_success :id => nil

end

end

...



GET XML view

xml.instruct!

@course.to_xml



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>’


curl -i -X DELETE http://localhost:3000/courses/4


http://coronet.iicm.edu/mmis2/examples/ws/rest/rest_courses.zip

http://coronet.iicm.edu/mmis2/examples/ws/rest/rest_courses.zip

REST-RPC Hybrid Architectures (1)

Services somewhere between RESTful and RPC services


search&tags=penguin

Both method and scoping information is in URL

HTTP is used as an envelope format




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


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/


http://www.programmableweb.com/

http://www.programmableweb.com/tag/ajax

http://www.2lingual.com/

http://www.ajaxonomy.com/deliciousspy/

http://flickr.mathewvp.com/

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


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

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


http://webservices.xml.com/pub/a/ws/2003/09/30/soa.html

http://webservices.xml.com/pub/a/ws/2001/04/04/webservices/index.html

http://webservices.xml.com/pub/a/ws/2001/04/04/webservices/index.html

http://webservices.xml.com/pub/a/ws/2002/02/12/webservicefaqs.html?page=1

http://webservices.xml.com/pub/a/ws/2002/02/12/webservicefaqs.html?page=1

http://java.sun.com/developer/technicalArticles/WebServices/soa2/index.html

http://java.sun.com/developer/technicalArticles/WebServices/soa2/index.html

http://webservices.xml.com/

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


http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

http://xml.com/pub/at/34

http://www.xml.com/pub/a/2006/04/19/rest-on-rails.html

http://webservices.xml.com/pub/a/ws/2002/02/06/rest.html

RESTful Web Serviceskti.tugraz.at/staff/denis/courses/mmis2/material/slides_ws_main.pdf · RESTful...

Documents

Transcript of RESTful Web Serviceskti.tugraz.at/staff/denis/courses/mmis2/material/slides_ws_main.pdf · RESTful...