RESTful webservices

1. RESTful
Webservices
Mohammed Luqman Shareef

2. Agenda
• Introduction to Webservices
• SOAP based webservices
• RESTful webservices
• Implementation of RESTful webservices
• SOAP vs. REST
• Why SOAP?
• Why REST?
• Q&A
9/29/2013www.luqmanshareef.com
2

3. 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.”
9/29/2013www.luqmanshareef.com
3

4. 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
2010-02-08www.luqmanshareef.com
4
Components of a SOAP based web service

5. 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.
9/29/2013www.luqmanshareef.com
5

6. 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
9/29/2013www.luqmanshareef.com
6
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. 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?
9/29/2013www.luqmanshareef.com
7

8. 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/29/2013www.luqmanshareef.com
8

9. RESTful web services
• 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.
9/29/2013www.luqmanshareef.com
REpresentational State Transfer
9

10. RPC vs REST
• 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
9/29/2013www.luqmanshareef.com
 Every useful data object has an address
 Resources themselves are the targets for
method calls
 The list of methods is fixed for all resources
RPC
REST
10

11. RESTful web services contd…
9/29/2013www.luqmanshareef.com
Client side
> Easy to experiment in browser
> Broad programming language support
> Choice of data formats
> bookmarkable
Server side
> Uniform Interface
> Cacheable
> Scalable
> Easy failover
Benefits
> Resource identification through URI
> Uniform interface
GET/PUT/POST/DELETE
> Self-descriptive messages
> Stateless interactions through hyperlinks
Principles
11

12. 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.
9/29/2013www.luqmanshareef.com
12

13. Product service as RESTful
9/29/2013
www.luqmanshareef.com
Request
GET /products/X123 HTTP/1.1
Host: vendorx.com
Accept: application/xml
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
<?xml version="1.0"?>
<Products xmlns="…">
<Product id=“X123”>
…
</Product>
</Products>
Method Resource
Representation
State
transfer
13

14. Developing a RESTful web service
using JAX-RS
9/29/2013www.luqmanshareef.com
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) {
...
…
}
}
14

15. JAX-RS REST Annotations
Annotation Description
@Path
The @Path annotation's value is a relative URI path indicating where the Java class will be hosted, for
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}.
@GET The @GET 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 HTTP GET
requests. The behavior of a resource is determined by the HTTP method to which the resource is
responding.
@POST The @POST 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 HTTP POST
requests. The behavior of a resource is determined by the HTTP method to which the resource is
responding.
@PUT The @PUT 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 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.
9/29/2013www.luqmanshareef.com
15

16. JAX-RS REST Annotations
Annotation Description
@HEAD
The @HEAD 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 HTTP
HEAD requests. The behavior of a resource is determined by the HTTP method to which the
resource is responding.
@PathParam
The @PathParam annotation is a type of parameter that you can extract for use in your resource
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.
@QueryParam The @QueryParam annotation is a type of parameter that you can extract for use in your resource
class. Query parameters are extracted from the request URI query parameters.
@Consumes The @Consumes annotation is used to specify the MIME media types of representations a resource
can consume that were sent by the client.
@Produces The @Produces annotation is used to specify the MIME media types of representations a resource
can produce and send back to the client, for example, "text/plain".
9/29/2013www.luqmanshareef.com
16

17. Using Spring framework
9/29/2013www.luqmanshareef.com
17

18. 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.
9/29/2013www.luqmanshareef.com
18

19. 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
9/29/2013www.luqmanshareef.com
19

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.
9/29/2013www.luqmanshareef.com
20

21. 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.
9/29/2013www.luqmanshareef.com
21

22. 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.
9/29/2013www.luqmanshareef.com
22

23. 2010-02-08www.luqmanshareef.com
23
Questions?

24. 2010-02-08www.luqmanshareef.com
24