REST (Representational state transfer) has become very popular and in fact it was always there but we just didn’t see it until Roy Fielding presented his doctoral dissertation. It gives us the power of distributed computing without the hassle of redefining the protocol to access those distributed objects.

The current peers of REST can be EJB and the so called Service oriented architectures which again requires their own custom protocols such as RMI or SOAP. Unlike REST works with HTTP protocol and hence leverage whats already there. We can define distributed objects using REST and access those object using simple HTTP protocols such as GET, PUT, DELETE etc.

Furthermore, the REST based server side object can be deployed in a simple web container which makes it easy enough to use with Spring and a no EJB approach. Think about this that if you develop a RESTful service then it will be useful for a mobile view as well as a desktop because the protocol to access it is light-weight HTTP

Enough of theory… now lets just build something which will be useful in daily life. An example of a very common service is address validation. We all need to verify whether the zipcode entered by the user is valid. I understand that google or some other vendor will already have such a service but for now lets just build that on a smaller scale.

Simple Zip Locator REST App

To build a REST app we need a provider that can run the distributed object in the Servlet container. For that we are using Apache CXF. This will be a no database and in-memory example for simplicity.

1. First we need something to hold zip code information. Lets name it ZipcodeDetails 

@XmlRootElement
public class ZipcodeDetails implements Serializable
{
private String zipcodeId;
private String cityName;
private String state;
}

2.  The service name will be FindZipcodeService. Please note that we are defining that the results can be consumed as XML or JSON using @Produces annotation. We can define more Media types if needed. Also the @Path annotation is what leads us to these methods. Again if you are familiar with Spring MVC then it should be straight forward.

@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public class FindZipcodeService
{
@GET
@Path("findbyzipcode/{zipcode}")
public ZipcodeDetails findzipcodeDetails(@PathParam("zipcode") String zipcode) {..}
}

3.  This is how we can define the REST service using Apache CXF in applicationContext,.xml

<bean class="org.apache.cxf.jaxrs.provider.XMLBeansElementProvider" id="xmlBeanProvider">
<bean class="org.apache.cxf.jaxrs.provider.XMLBeansJSONProvider" id="jsonProvider">       <jaxrs:server address="/" id="zipcodeService">
<jaxrs:servicebeans>
<ref bean="findZipcodeService">
</ref></jaxrs:servicebeans>
<jaxrs:providers>
<ref bean="xmlBeanProvider">
<ref bean="jsonProvider">
</ref></ref></jaxrs:providers>
</jaxrs:server>
</bean>
</bean>

4.  Main project dependencies are Apache CXF and JaxRS

<dependency>
<groupid>org.apache.cxf</groupid>
<artifactid>cxf-rt-transports-http</artifactid>
<version>${cxf.version}</version>
</dependency>
<dependency>
<groupid>org.apache.cxf</groupid>
<artifactid>cxf-rt-frontend-jaxrs</artifactid>
<version>${cxf.version}</version>
</dependency>
<dependency>
<groupid>javax.ws.rs</groupid>
<artifactid>jsr311-api</artifactid>
<version>1.1</version>
</dependency>

5.  Finally your Web XML needs to define the Dispatcher servlet to handle REST related request as shown.

<servlet>
<servlet-name>CXFServlet</servlet-name>
<servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>CXFServlet</servlet-name>
<url-pattern>/rest/*</url-pattern>
</servlet-mapping>

6.  When you deploy this on Jetty/Tomcat or any Server give the context path to “/”. This way the URL will be formed as http://localhost:8080/rest/findbyzipcode/55401

Conclusion

This application can be deployed on cloud. see instructions here. For demo purpose we have deployed a full blown ziplocator service to cloud foundry with all US based zip codes. http://ziplocator.cloudfoundry.com e.g. http://ziplocator.cloudfoundry.com/rest/findbyzipcode/55426 as you can see that we can embed this URL in a jQuery to do validation or may be do auto-complete for city and state.

Downloads (complete source code)

• HTTP https://github.com/spinachsoftware/ZipRESTWebApp
• Git Read-Only http://github.com/spinachsoftware/ZipRESTWebApp.git