Web Services (NSWI145)Lecture 07: RESTful Web Services

Martin Nečaský, Ph.D.Faculty of Mathematics and Physics

Charles University in Prague, Czech Republic

What is REST? REpresentation State Transfer software architectural style for building distributed

hypermedia systems set of following architectural principles

resource orientation unique resource identification stateless client/server interaction uniform interface

e.g. Web architecture is based on the same principles as REST but REST principles were derived from the architecture of

Web (Roy Fielding dissertation)

Principle 1: Resource Orientation resource = concrete or even abstract thing/action we

want to publish everything is resource in REST

each resource has its representation = document that can be sent between communicating peers representation format needs to be established

• different (meta-)formats may be used (e.g. HTML, XML, JSON, RDF, AtomPub, ...)

• each resource can have more representations (in different formats)

representation contains links to related resources• representation format must support links• applications which consume resources navigate instead of calling

Principle 2: Unique Resource Identification

each resource has unique ID (name) universal syntax for resource IDs is necessary, e.g. URI ID serves not just as a name but also as a means of accessing

resource representation parametrized IDs

http://www.company.org/customer?name=John

distinguish resource ID from resource representation ID (e.g. HTML, XML, JSON, RDF documents) if resource = document then resource ID = resource

representation ID otherwise we need strategy to allow clients to request

specific resource representation

Principle 2: Unique Resource Identification

direct dereferencing resource ID is not dereferenceable client has to know particular resource

representation IDs e.g. Twitter uses direct dereferencing

https://api.twitter.com/1/statuses/user_timeline.jsonhttps://api.twitter.com/1/statuses/user_timeline.xml

Principle 2: Unique Resource Identification

303 URIs resource ID is dereferenceable HTTP mechanism two requests• client requests resource ID and specified preferred

resource representation format – server sends resource representation ID

• client requests resource representation ID

Principle 2: Unique Resource Identification

Server

clientGET /customer?name=JohnHost: www.company.orgAccept: text/xml

Server

clientHTTP/1.1 303 See OtherLocation: http://www.company.org/customer.xml?name=John

Server

clientGET /customer.xml?name=JohnHost: www.company.orgAccept: text/xml

Principle 2: Unique Resource Identification

how to set-up 303 URIs? e.g. Apache HTTPD (.htaccess file)

RewriteCond %{HTTP_ACCEPT} application/rdf\+xml RewriteRule ^customer customer.rdf [R=303]

http://www.company.org/customer?name=John

http://www.company.org/customer.xml?name=John

Principle 2: Unique Resource Identification

avoid parametrized resource ID e.g.

http://www.company.org/customer/John

instead ofhttp://www.company.org/customer?name=John

RewriteCond %{HTTP_ACCEPT} application/rdf\+xml RewriteRule ^customer/([a-zA-Z]+)$ customer.rdf?name=John

Principle 3: Stateless Client/Server Communication

request/response message exchange separation of concerns principle

clients separated from servers by interface clients are not concerned with data storage and

(most) application logic servers are not concerned with user interface or

state (server simplicity and scalability) independent evolution of clients and server e.g. HTTP request/response, SOAP

request/response message exchange pattern, etc.

Principle 3: Stateless Client/Server Communication

stateless communication no state in server-side applications move state to clients and/or resources

resource state is the same for every client client changes to resource state affect all other

clients client state is specific for each particular client

communication state

Principle 4: Resource Manipulation

uniform interface for resource manipulation small set of operations which apply for everything• e.g. CRUD operations (Create, Retrieve, Update, Delete)

small set of verbs which apply to large set of nouns• if many applications need new verb, uniform interface

can be extended do not encode verbs into resource identifiers

http://www.company.org/addCustomer?name=John

Principle 4: Resource Manipulation when HTTP protocol is used, following four operations are

usually considered GET = requests representation of the specified resource

• read-only operation, should be safe = should not cause any side-effects PUT = uploads representation of the specified resource

• write operation, should be idempotent– idempotent = may cause side effects but its multiple calls cause the same effect– being idempotent means being simple = identical request causes the same

state change independently of how many times it has been called

DELETE = deletes the specified resource• write operation, should be idempotent

POST = submits data to be processed to the specified resource• it can update the resource• generally not safe and not idempotent

RESTful Web Services

RESTful Web Service enables manipulation with set of resources typically uses XML, JSON or RDF for resource

representation uses URLs as resource identifiers stateless HTTP methods GET/PUT/DELETE/POST for

resource manipulation like Web application but for machines instead

of humans

RESTful Web Services

Operation Resource representing collection of individuals

Resource representing individual

GET List members in collection• e.g. weekly list public contracts

Retrieve individual• e.g. retrieve public contract

PUT Update collection with another one• e.g. replace weekly list of

public contracts at the beginning of new week

Update individual• e.g. update public contract

representation with new representation

DELETE Delete entire collection• e.g. delete weekly list of

public contracts

Delete individual• e.g. delete public contract

POST Create member of collection with auto-ID• e.g. add new public contract to

the collection and generate its ID

Create part of individual• e.g. create public contract

tender

JAX-RS (Jersey Impl.) with Tomcat + Eclipse

download Jersey https://jersey.dev.java.net/ (A zip of Jersey containing the Jersey jars, core dependencies (it does not provide

dependencies for third party jars beyond those for JSON support) and JavaDoc)

create new Eclipse Dynamic Web Project ProjectName Apache Tomcat as Target runtime

ProjectName project > Properties Java Build Path > Libraries > Add External JARs...

• add JARs from Jersey zip copy JARs from Jersey zip to WEB-INF/lib modify WEB-INF/web.xml

JAX-RS (Jersey Impl.) with Tomcat + Eclipse

class PublicContracts01 in Procurement_REST_WS project http://localhost:8080/Procurement_REST_WS/res

ources/PublicContracts01/ provides simple representation of “List of public

contracts” resource in plain text, HTML and XML basic JAX-RS annotations• @Path• @GET• @Produces

JAX-RS (Jersey Impl.) with Tomcat + Eclipse

test with cURL (curl_PublicContracts01.bat) http://curl.haxx.se/download.html

JAX-RS (Jersey Impl.) with Tomcat + Eclipse

class PublicContracts02 in Procurement_REST_WS project http://localhost:8080/Procurement_REST_WS/resources/PublicC

ontracts02/ getPublicContract method which returns XML or JSON

representation of public contract to GET request• class PublicContract• JAXB annotation (provides XML and JSON binding)

– @XmlRootElement

listContracts method returns XML or JSON representation of all public contracts in collection to GET request

listContractsHTML method returns HTML representation of all public contracts in collection to GET request

JAX-RS annotations• @Path – path with path parameter• @PathParam – association of path parameter with method parameter

JAX-RS (Jersey Impl.) with Tomcat + Eclipse

test http://localhost:8080/Procurement_REST_WS/res

ources/PublicContracts02/ http://localhost:8080/Procurement_REST_WS/res

ources/PublicContracts02/4

JAX-RS (Jersey Impl.) with Tomcat + Eclipse

class PublicContracts03 in Procurement_REST_WS project http://localhost:8080/Procurement_REST_WS/res

ources/PublicContracts03/ putPublicContract updates existing or creates new

public contract deletePublicContract deletes existing public

contract JAX-RS annotations• @PUT• @DELETE

JAX-RS (Jersey Impl.) with Tomcat + Eclipse

test with cURL (curl_PublicContracts03.bat)

JAX-RS (Jersey Impl.) with Tomcat + Eclipse

class PublicContracts04 in Procurement_REST_WS project http://localhost:8080/Procurement_REST_WS/res

ources/PublicContracts04/ createPublicContract creates new contract on

POST request JAX-RS annotations• @POST

JAX-RS (Jersey Impl.) with Tomcat + Eclipse

test with form_PublicContracts04.html