Introduction
REST APIs serve as the backbone of millions of web applications. This is one of the most commonly used web service standards in today’s world. The JAX-RS provides the REST support in Java and has lots of features that help us build scalable web services. In this article we are going to explore some of the JAX-RS features that are important to know while building a web service.
Bootstrapping a JAX-RS application
It is very simple to start a JAX-RS application. All you need to do is to create a subclass of javax.ws.rs.core.Application on your classpath. The below given sample explains how you will do that:
|
import javax.ws.rs.core.Application;
@ApplicationPath(“api”)
public class SampleWebAPIApplication extends
Application { }
|
The annotation @ApplicationPath provides the context root for all your APIs. In this case the APIs will have a URI starting with ‘/api’. So if you have an API to provide employee details, the URI will look like “http://www.example.com/api/v2/employee/” here the “/v2/” stands for versioning. It’s always a good practice to include versioning while creating APIs. This will be helpful when you want the same resource in custom APIs for different clients.
Defining REST endpoints
The REST endpoints serve as the connection point with the client. The JAX-RS specification has given the @Path annotation to map each HTTP (PUT, DELETE, POST, GET) method to a java method. Consider the following example:
|
public class EmployeeDatabse {
@GET
@Path(“/{id}”)
public Response getNameById(@PathParam(“id”) Long id,
@QueryParam(“name”) @DefaultValue(“”) String name) {
@POST
public Response getNameById(Employee employee, @Context UriInfo uriInfo) {
// …
}
// …
}
|
Here the entire class is mapped to “/employee” with different HTTP methods. The @PathParam is used for getting the value of a path variable and the @QueryParam is used for retrieving values for a query parameter of a URL.
JAX-RS Providers
Providers are extensions of JAX-RS that are responsible for providing functionality to the JAX-RS runtime. Mainly two types of providers are there. Exception mapping providers and Entity providers.
Exception Mapping Providers
These are responsible for mapping services between JAX-RS response and Java exceptions. The ExceptionMapper interface is provided when a resource method throws a runtime exception. The response provided by these exception mappers are treated as same as the response provided by the resource methods.
Entity Providers
Entity providers provide marshalling / unmarshalling service between Java types and the resource representations (XML/JSON etc.).
The MessageBodyReader interface is an entity provider that is used for deserializing a resource representation into a Java type. The reverse operation is performed by another entity provider interface named MessageBodyWriter.
Exception Handling
The exceptions that are thrown by a resource method are caught by the JAX-RS runtime and they are converted into error responses. By default they are converted into a “HTTP 500 – Server Error” message. There are two ways in JAX-RS to deal with exceptions, the first method is to throw “WebApplicationException” that can customize error response messages. The second method is to use the built in response mechanism of the JAX-RS runtime that will send a default Response to the client when an exception is caught.
Summary
When dealing with REST implementation using JAX-RS, there are some points that one must know to make use of its full potential. These concepts discussed here will help you build web services that conform to the REST principle.