This document provides an overview of RESTful web services and the REST architectural style. It defines the key principles of REST including resource orientation, unique resource identification, stateless communication between client and server, and using a uniform interface to manipulate resources. It describes how RESTful web services allow resources to be manipulated via HTTP methods like GET, PUT, DELETE and POST. It also provides examples of implementing RESTful web services using JAX-RS with Jersey on Tomcat and testing with cURL.

1. Web Services (NSWI145)
Lecture 07: RESTful Web Services
Martin Nečaský, Ph.D.
Faculty of Mathematics and Physics
Charles University in Prague, Czech Republic

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

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

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

5. 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.json
https://api.twitter.com/1/statuses/user_timeline.xml

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

7. Principle 2: Unique Resource Identification
Server
GET /customer?name=John
Host: www.company.org
client Accept: text/xml
Server
HTTP/1.1 303 See Other
Location:
client http://www.company.org/customer.xml?name=John
Server
GET /customer.xml?name=John
Host: www.company.org
client Accept: text/xml

8. 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/ http://www.company.org/
customer?name=John customer.xml?name=John

9. Principle 2: Unique Resource Identification
 avoid parametrized resource ID
 e.g.
http://www.company.org/customer/John
 instead of
http://www.company.org/customer?name=John
RewriteCond %{HTTP_ACCEPT} application/rdf+xml
RewriteRule ^customer/([a-zA-Z]+)$ customer.rdf?name=John

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

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

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

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

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

15. RESTful Web Services
Operation Resource representing Resource representing
collection of individuals individual
GET List members in collection Retrieve individual
• e.g. weekly list public contracts • e.g. retrieve public contract
PUT Update collection with Update individual
another one • e.g. update public contract
• e.g. replace weekly list of representation with new
public contracts at the representation
beginning of new week
DELETE Delete entire collection Delete individual
• e.g. delete weekly list of • e.g. delete public contract
public contracts
POST Create member of Create part of individual
collection with auto-ID • e.g. create public contract
• e.g. add new public contract to tender
the collection and generate its
ID

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

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

18. JAX-RS (Jersey Impl.) with Tomcat + Eclipse
 test with cURL (curl_PublicContracts01.bat)
 http://curl.haxx.se/download.html

19. JAX-RS (Jersey Impl.) with Tomcat + Eclipse
 class PublicContracts02 in Procurement_REST_WS project
 http://localhost:8080/Procurement_REST_WS/resources/Public
Contracts02/
 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

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

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

22. JAX-RS (Jersey Impl.) with Tomcat + Eclipse
 test with cURL (curl_PublicContracts03.bat)

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

24. JAX-RS (Jersey Impl.) with Tomcat + Eclipse
 test with form_PublicContracts04.html