Restful Web Services

REST is the acronym for REpresentational State Transfer. REST is an architectural style for developing applications that can be accessed over the network. REST architectural style was brought in light by Roy Fielding in his doctoral thesis in 2000.

Restful Web Services

Restful Web Services is a stateless client-server architecture where web services are resources and can be identified by their URIs.

REST Client applications can use HTTP GET/POST methods to invoke Restful web services. REST doesn’t specify any specific protocol to use, but in almost all cases it’s used over HTTP/HTTPS. When compared to SOAP web services, these are lightweight and doesn’t follow any standard. We can use XML, JSON, text or any other type of data for request and response.

Java RESTful Web Services API

Java API for RESTful Web Services (JAX-RS) is the Java API for creating REST web services. JAX-RS uses annotations to simplify the development and deployment of web services. JAX-RS is part of JDK, so you don’t need to include anything to use it’s annotations.

Restful Web Services Annotations

Some of the important JAX-RS annotations are:

• @Path: used to specify the relative path of class and methods. We can get the URI of a webservice by scanning the Path annotation value.
• @GET, @PUT, @POST, @DELETE and @HEAD: used to specify the HTTP request type for a method.
• @Produces, @Consumes: used to specify the request and response types.
• @PathParam: used to bind the method parameter to path value by parsing it.

Restful Web Services and SOAP

1. SOAP is a protocol whereas REST is an architectural style.
2. SOAP server and client applications are tightly coupled and bind with the WSDL contract whereas there is no contract in REST web services and client.
3. Learning curve is easy for REST when compared to SOAP web services.
4. REST web services request and response types can be XML, JSON, text etc. whereas SOAP works with XML only.
5. JAX-RS is the Java API for REST web services whereas JAX-WS is the Java API for SOAP web services.

REST API Implementations

There are two major implementations of JAX-RS API.

1. Jersey: Jersey is the reference implementation provided by Sun. For using Jersey as our JAX-RS implementation, all we need to configure its servlet in web.xml and add required dependencies. Note that JAX-RS API is part of JDK not Jersey, so we have to add its dependency jars in our application.
2. RESTEasy: RESTEasy is the JBoss project that provides JAX-RS implementation.

Java Restful Web Services Tutorial

Let’s see how easy to create Restful web service using Jersey and then RESTEasy. We will be exposing following methods over HTTP and use Chrome Postman extension to test these.

URI	HTTP METHOD	DESCRIPTION
/person/{id}/getDummy	GET	Returns a dummy person object
/person/add	POST	Adds a person
/person/{id}/delete	GET	Delete the person with ‘id’ in the URI
/person/getAll	GET	Get all persons
/person/{id}/get	GET	Get the person with ‘id’ in the URI

REST api is used for create, read, update, and delete (CRUD) operations and HTTP methods.

1.POST - to create or update a resource on the server.

2.GET - to retrieve a resource.

3.PUT - to update a resource.

4.DELETE - to delete a resource.

Annotations	Package Details
@GET	import javax.ws.rs.GET;
@Produces	import javax.ws.rs.Produces;
@Path	import javax.ws.rs.Path;
@PathParam	import javax.ws.rs.PathParam;
@QueryParam	import javax.ws.rs.QueryParam;
@POST	import javax.ws.rs.POST;
@Consumes	import javax.ws.rs.Consumes;
@FormParam	import javax.ws.rs.FormParam;
@PUT	import javax.ws.rs.PUT;
@DELETE	import javax.ws.rs.DELETE;

Annotate your Get request methods with @GET

@GET

public String getHTML() {

...

}

@Produces

@Produces annotation specifies the type of output this method (or web service) will produce.

@GET
@Produces("application/xml")
public Contact getXML() {
  ...
}

@GET
@Produces("application/json")
public Contact getJSON() {
  ...

}

@Path

@Path annotation specify the URL path on which this method will be invoked.

@GET
@Produces("application/xml")
@Path("xml/{firstName}")
public Contact getXML() {
  ...

}

@PathParam

We can bind REST-style URL parameters to method arguments using @PathParam annotation as shown below.

@GET
@Produces("application/xml")
@Path("xml/{name}")
public Product getXML(@PathParam("name") String name) {
  Product product = productService.findByFirstName(name);
  return product ;
}


@GET
@Produces("application/json")
@Path("json/{name}")
public Product getJSON(@PathParam("name") String name) {
  Product product = productService.findByFirstName(name);
  return product ;

}

@QueryParam

Request parameters in query string can be accessed using @QueryParam annotation as shown below.

@GET
@Produces("application/json")
@Path("json/productList")
public ProductList getProductList(@QueryParam("start") int start, @QueryParam("limit") int limit) {
  ProductList list = new ProductList(productService.listCompanies(start, limit));
  return list;

}

The example above returns a list of companies (with server side pagination) which can be displayed with rich clients implemented using Ext-js or jQuery. .

@POST

Annotate POST request methods with @POST.

@POST
@Consumes("application/json")
@Produces("application/json")
public getProduct<Product> create(Product product) {
...

}

@Consumes

The @Consumes annotation is used to specify the MIME media types a REST resource can consume.

@PUT
@Consumes("application/json")
@Produces("application/json")
@Path("{productId}")
public ProductResponse<Product> update(Product product) {
...

}

@FormParam

The REST resources will usually consume XML/JSON for the complete Entity Bean. Sometimes, you may want to read parameters sent in POST requests directly and you can do that using @FormParam annotation. GET Request query parameters can be accessed using @QueryParam annotation.

@POST
public String save(@FormParam("name") String name,
    @FormParam("id") String id) {
      ...

  }

@PUT

Annotate PUT request methods with @PUT.

@PUT
@Consumes("application/json")
@Produces("application/json")
@Path("{id}")
public Update<Product> update(Product product) {
...

}

@DELETE

Annotate DELETE request methods with @DELETE.

@DELETE
@Produces("application/json")
@Path("{contactId}")
public RestResponse<Contact> delete(@PathParam("contactId") int contactId) {
...

}

Example Restful webservice Project