RESTful

Webservices

Mohammed
Luqman Shareef
 2

www.luqmanshareef.com 04/29/20

Agenda
• Introduction to Webservices
• SOAP based webservices
• RESTful webservices
• Implementation of RESTful webservices
• SOAP vs. REST
• Why SOAP?
• Why REST?
• Q&A
 3

www.luqmanshareef.com 04/29/20

What is a webservice?
• There are too many definitions.

• Most of them are very specific to SOAP based services, and consider
WSDL and UDDI as its integral parts, like
▫ “Web service is a standard way of integrating Web-based applications
using the XML, SOAP, WSDL and UDDI open standards over an Internet
protocol backbone. ”

• There are too generic definitions as well, like

▫ “Web services are loosely coupled computing services that can reduce
the complexity of building business applications, save costs, and enable
new business models. Services running on an arbitrary machine can be
accessed in a platform- and language-independent fashion.”

▫ “Web Services can convert your applications into Web-applications.

Web Services are published, found, and used through the Web.”
 4

www.luqmanshareef.com 2010-02-08

Components of a SOAP based web service

XML (eXtensible Markup Language)
A uniform data representation and exchange
mechanism

SOAP (Simple Object Access Protocol)

Lightweight (XML-based) protocol for exchange
of information in a decentralized, distributed
environment

WSDL (Web Service Description Language)

XML format that describes the web service

UDDI (Universal Description Discovery and Integration)

Like yellow pages of Web services
 5

www.luqmanshareef.com 04/29/20

Lets take a scenario

• An inventory database of a Supply chain management system
gets updated with products’ information from various vendors.

• What is the best way to communicate?

▫ Each Vendor exposes a webservice (say SOAP based).

▫ Each webservice has its own contract(WSDL) defined, consisting

of various operations, input and output message types, bindings
etc.

▫ The consumer application needs to understand the contracts,

create a client stub to communicate with each vendor. For every
new vendor a separate stub is needed.
 6

www.luqmanshareef.com 04/29/20

SOAP based webservice

• Each Vendor shall expose a webservice through an end point like
http://www.vendorX.com/the-endpoint
▫ Operations can be:
 GetProduct
 AddProduct
 DeleteProduct
• For Example GetProduct message will look like

HTTP Header

SOAP Envelope
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
<env:Body>
<v:GetProduct xmlns:v="http://vendorX.com/">
<v:ProdId>X123</v:ProdId>
<v:Name>Hard Drive</v:Name>
</v:GetProduct>
</env:Body>
</env:Envelope>
 7

www.luqmanshareef.com 04/29/20

SOAP based webservice

• Whether it is a pull operation or a push, (i.e., request for
the product info, or add a new product) it is simply a
get/post. And the content shared is always the product
information in a standard format.

• Why do we need different contracts from different

vendors?

• Can’t we use any of the standards prevailing in the

industry to make life easier?

• Why not a simple GET operation be done with HTTP

GET method?
 8

www.luqmanshareef.com 04/29/20

HTTP Protocol
• Lets use standard HTTP protocol.

• It can be accessed via a URL (Uniform Resource Locator) like

▫ http://www.vendorx.com/products/x123

• It has standard methods to

▫ Retrieve ( GET )
▫ Create ( POST )
▫ Update ( PUT )
▫ Delete (DELETE )

• Payload can be directly added to http message. No need to

wrap it in another protocol.
 9

www.luqmanshareef.com 04/29/20

RESTful web services

REpresentational State Transfer
• It is a simple stateless architecture that generally runs over HTTP.

• The focus is on a resource in the system

▫ Ex: an Employee, an Account, a Product etc.

• Each unique URL is a representation of some object

Ex : http://www.vendorx.com/products
http://www.vendorx.com/products/x123

• HTTP methods (GET/POST/…) operates on the resource.

• Object state is transferred and stored at client.

• Representation of the resource state in XML, JSON etc.

 10

RPC vs REST
www.luqmanshareef.com 04/29/20

RPC

• Every object has its own unique methods

• Methods can be remotely invoked over the Internet
• A single URI represents the end-point, and that's the
only contract with the Web
• Data hidden behind method calls and parameters
• Data is unavailable to Web applications

REST

 Every useful data object has an address

 Resources themselves are the targets for method
calls
 The list of methods is fixed for all resources
 11

www.luqmanshareef.com 04/29/20

RESTful web services contd…

Principles
> Resource identification through URI
> Uniform interface
GET/PUT/POST/DELETE
> Self-descriptive messages
> Stateless interactions through hyperlinks

Benefits
Server side Client side
> Uniform Interface > Easy to experiment in browser
> Cacheable > Broad programming language support
> Scalable > Choice of data formats
> Easy failover > bookmarkable
 12

www.luqmanshareef.com 04/29/20

Six characteristics of REST:

• Uniform interface
• Decoupled client-server interaction
• Stateless
• Cacheable
• Layered
• Extensible through code on demand (optional)

* Services that do not conform to the above required contstraints are not strictly
RESTful web services.
 13

www.luqmanshareef.com

Product service as RESTful

Request
GET /products/X123 HTTP/1.1
Host: vendorx.com
Accept: application/xml

Method Resource
Response
HTTP/1.1 200 OK
Date: Tue, 09 Feb 2010 11:41:20 GMT
Server: Apache/1.3.6
Content-Type: application/xml; charset=UTF-8

State <?xml version="1.0"?>

transfer <Products xmlns="…">
Representation
<Product id=“X123”>
…
</Product>
</Products> 04/29/20
 14

www.luqmanshareef.com 04/29/20

Developing a RESTful web service

using JAX-RS
package com.vendorx.products;

import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;

@Path("/employees/{pid}")
public class Product{
@GET
@Produces("text/xml")
public String getProduct(@PathParam(“pid") String pId) {
...
…
}
}
 15

www.luqmanshareef.com 04/29/20

JAX-RS REST Annotations

Annotation Description
The @Path annotation's value is a relative URI path indicating where the Java class will be hosted, for
@Path example, /helloworld. You can also embed variables in the URIs to make a URI path template. For
example, you could ask for the name of a user, and pass it to the application as a variable in the URI, like
this, /helloworld/{username}.

The @GET annotation is a request method designator and corresponds to the similarly named HTTP
@GET method. The Java method annotated with this request method designator will process HTTP GET
requests. The behavior of a resource is determined by the HTTP method to which the resource is
responding.

The @POST annotation is a request method designator and corresponds to the similarly named HTTP
@POST method. The Java method annotated with this request method designator will process HTTP POST
requests. The behavior of a resource is determined by the HTTP method to which the resource is
responding.

The @PUT annotation is a request method designator and corresponds to the similarly named HTTP
@PUT method. The Java method annotated with this request method designator will process HTTP PUT
requests. The behavior of a resource is determined by the HTTP method to which the resource is
responding.

@DELETE The @DELETE annotation is a request method designator and corresponds to the similarly named HTTP
method. The Java method annotated with this request method designator will process HTTPDELETE
requests. The behavior of a resource is determined by the HTTP method to which the resource is
responding.
 16

www.luqmanshareef.com 04/29/20

JAX-RS REST Annotations

Annotation Description
The @HEAD annotation is a request method designator and corresponds to the similarly named
@HEAD HTTP method. The Java method annotated with this request method designator will process HTTP
HEAD requests. The behavior of a resource is determined by the HTTP method to which the
resource is responding.

The @PathParam annotation is a type of parameter that you can extract for use in your resource
@PathParam class. URI path parameters are extracted from the request URI, and the parameter names
correspond to the URI path template variable names specified in the @Path class-level annotation.

The @QueryParam annotation is a type of parameter that you can extract for use in your resource
@QueryParam
class. Query parameters are extracted from the request URI query parameters.

The @Consumes annotation is used to specify the MIME media types of representations a resource
@Consumes can consume that were sent by the client.

The @Produces annotation is used to specify the MIME media types of representations a resource
@Produces can produce and send back to the client, for example, "text/plain".
 17

www.luqmanshareef.com 04/29/20

Using Spring framework

 18

www.luqmanshareef.com 04/29/20

Arguments: SOAP vs. REST

• SOAP based webservices are too complex for a
web based service.
• How about transactions and reliability in REST?
• SOAP based webservices are protocol
independent.
• REST operations are limited (only http methods)
• SOAP has built-in error handling.
• REST is easy to test (in any browser)
• SOAP is not only for Web.
• REST development is faster and easier.
 19

www.luqmanshareef.com 04/29/20

Arguments: SOAP vs. REST

• REST has better performance and scalability.
• SOAP has many extensions built WS-* (security,
transaction etc.)
• A service offered in a REST style will be easier to
consume than some complex API:
▫ Lower learning curve for the consumer
▫ Lower support overhead for the producer
• What happens when you need application semantics that
don't fit into the GET / PUT / POST / DELETE generic
interfaces and representational state model?
• These interfaces are sufficiently general. Other interfaces
considered harmful because they increase the costs of
consuming particular services
 20

www.luqmanshareef.com 04/29/20

Why REST?
• Exposing a public API over the internet to handle CRUD operations on data.

• REST permits many different formats like XML, JSON etc.

• REST reads can be cached.

• REST is concise. No need of additional messaging layer.

• REST is stateless. If an operation needs to be continued just REST doesn’t help.

• Easy to test (in any browser, no need of a new client to write)

• REST is particularly useful for restricted-profile devices such as mobile and PDAs for
which the overhead of additional parameters like headers and other SOAP elements
are less.
 21

www.luqmanshareef.com 04/29/20

Why SOAP?
• SOAP is not only for Web. It has its own protocol.

• SOAP Exposes application logic (not data) as service. Exposes named operations.

• Can implement stateful web services.

• SOAP Web services are useful in handling asynchronous processing and invocation.

• SOAP has additional feature built on top of it which REST doesn’t.

▫ WS-Security
▫ WS-Reliable Messaging
▫ WS-Atomic Transactions

• Most real-world applications are not simple and support complex operations, which require
conversational state and contextual information to be maintained. With the SOAP
approach, developers need not worry about writing this plumbing code into the application
layer themselves.
 22

www.luqmanshareef.com 04/29/20

WSDL 2.0
• WSDL 2.0 is tailored for SOAP-based Web services

• However, HTTP binding in WSDL 2.0 allows for good description of HTTP services
▫ <binding name="HttpBinding" interface="m:GetTemperature"
type="http://www.w3.org/2005/08/wsdl/http">
<operation ref="m:location" whttp:method="GET"
whttp:location="{country}/{city}"/>
</binding>

• It allows for an HTTP GET on http://weather.example/country/city:

▫ HTTP/1.1 200 Here's the temperature for you

Content-Type: application/xml
…

<weather xmlns="…">
<temperature>23</temperature>
</weather>

• All HTTP methods are supported.

 23

www.luqmanshareef.com 2010-02-08

Questions?
 24

www.luqmanshareef.com 2010-02-08