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