Building REST APIs with RESTEasy

In this tutorial, learn to build REST APIs using JAX-RS 2.0 and RESTEasy 3.1.2.Final and deploy in Servlet 3.0 container, by configuring resteasy-servlet-initializer and @ApplicationPath.

Table of Contents

Development environment
RESTEasy Maven dependencies
Create REST resources
Register REST resources in Servlet 3.0 container
Other used classes 
Demo

Development environment

RESTEasy 3.1.2.Final
Eclipse Neon.3
JDK 1.8
Tomcat 7

RESTEasy Maven dependencies

pom.xml file with necessary dependencies.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>net.restfulapi.app</groupId>
	<artifactId>NetworkManagement</artifactId>
	<packaging>war</packaging>
	<version>0.0.1-SNAPSHOT</version>
	<name>NetworkManagement</name>
	<url>http://maven.apache.org</url>
	<repositories>
		<repository>
			<id>jboss</id>
			<name>jboss repo</name>
			<url>http://repository.jboss.org/nexus/content/groups/public/</url>
		</repository>
	</repositories>
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>3.2</version>
				<configuration>
					<source>1.8</source>
					<target>1.8</target>
				</configuration>
			</plugin>
		</plugins>
		<finalName>NetworkManagement</finalName>
	</build>
	<dependencies>
		<dependency>
			<groupId>org.jboss.resteasy</groupId>
			<artifactId>resteasy-jaxrs</artifactId>
			<version>3.1.2.Final</version>
		</dependency>
		<dependency>
			<groupId>org.jboss.resteasy</groupId>
			<artifactId>resteasy-jaxb-provider</artifactId>
			<version>3.1.2.Final</version>
		</dependency>
		<dependency>
			<groupId>org.jboss.resteasy</groupId>
			<artifactId>resteasy-servlet-initializer</artifactId>
			<version>3.1.2.Final</version>
		</dependency>
		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<version>3.8.1</version>
			<scope>test</scope>
		</dependency>
	</dependencies>
</project>

Create REST resources

In this example, I am creating a network management application API, exposing configurations as resources. It uses standard JAX-RS annotations e.g. @Path, @GET and @Produces.

One extra annotation @Formatted is used to output formatted content in response.

ConfigurationResource.java

import java.util.List;

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

import org.jboss.resteasy.annotations.providers.jaxb.Formatted;

import net.restfulapi.app.dao.ConfigurationDB;
import net.restfulapi.app.rest.domain.Configuration;
import net.restfulapi.app.rest.domain.Configurations;
import net.restfulapi.app.rest.domain.common.Status;

@Path("/configurations")
public class ConfigurationResource 
{
	@GET
	@Path("/")
	@Produces("application/xml")
	@Formatted
	public Configurations getConfigurations() {
		
		ConfigurationDB.createConfiguration("Some Content", Status.ACTIVE);
		ConfigurationDB.createConfiguration("Some More Content", Status.INACTIVE);
		
		List<Configuration> list = ConfigurationDB.getAllConfigurations();
		
		Configurations configurations = new Configurations();
		configurations.setConfigurations(list);
		configurations.setSize(list.size());
		
		return configurations;
	}
}

Register REST resources in Servlet 3.0 container

Now, let’s register ConfigurationResource as javax.ws.rs.core.Application.

NetworkApplication.java

import java.util.HashSet;
import java.util.Set;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

import net.restfulapi.app.rest.service.ConfigurationResource;

@ApplicationPath("/network-management")
public class NetworkApplication extends Application {

   private Set<Object> singletons = new HashSet<Object>();
   private Set<Class<?>> empty = new HashSet<Class<?>>();

   public NetworkApplication() {
      singletons.add(new ConfigurationResource());
   }

   @Override
   public Set<Class<?>> getClasses() {
      return empty;
   }

   @Override
   public Set<Object> getSingletons() {
      return singletons;
   }
}

After above configuration, you don’t need to make any change in web.xml.

web.xml

<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee https://www.oracle.com/java/technologies/;
	<display-name>Archetype Created Web Application</display-name>
</web-app>

Notice version="3.0" is first line. It is for making application servlet 3.0 compliant.

Other used classes

Now let’s see model classes.

Configurations.java

@XmlRootElement(name = "configurations")
@XmlAccessorType(XmlAccessType.FIELD)
public class Configurations 
{
	@XmlAttribute
	private Integer size;
	
	@XmlElement
	private Link link;
	
	@XmlElement
	private List<Configuration> configurations;

	//Removed getters and setters to minimize text; Please add in your code.
}

Configuration.java

@XmlRootElement(name="configuration")
@XmlAccessorType(XmlAccessType.FIELD)
public class Configuration 
{
	@XmlAttribute
	private Integer id;

	@XmlElement
	private Link link;

	@XmlElement
	private String content;

	@XmlElement
	private Status status;

	//Removed getters and setters to minimize text; Please add in your code.
}

ConfigurationDB.java

public class ConfigurationDB {
	private static Map<Integer, Configuration> configurationDB = new ConcurrentHashMap<Integer, Configuration>();
	private static AtomicInteger idCounter = new AtomicInteger();
	
	public static void createConfiguration(String content, Status status){
		Configuration c = new Configuration();
		c.setId(idCounter.incrementAndGet());
		c.setContent(content);
		c.setStatus(status);
		configurationDB.put(c.getId(), c);
	}
	
	public static List<Configuration> getAllConfigurations(){
		return new ArrayList<Configuration>(configurationDB.values());
	}
}

Demo

Now deploy the application in tomcat 7.
Hit the URL: http://localhost:8080/NetworkManagement/network-management/configurations

You will see the API response as given image.

Drop me your questions in comments section.

Happy Learning !!