REST API Tutorial

Create REST APIs with JAX-RS

Last Updated : September 30, 2021 By : Lokesh Gupta

In REST API Design Tutorial, we learned to put the REST principles onto the design process of a network
application. In this post, we will learn to create REST APIs for the same application using JAX-RS 2.0 (Java API for
RESTful Services).

Table of Contents

JAX-RS 2.0 Specification

JAX-RS 2.0 Annotations
Create Maven Application
Include JAX-RS Dependencies to Application
Create Resource Representations
Create REST Resource
Register Resource in runtime
Demo

1. JAX-RS Specification
JAX-RS provides portable APIs for developing, exposing, and accessing Web
applications designed and implemented in compliance with principles of REST
architectural style.

The Java EE 6 release took the first step towards standardizing RESTful web service APIs by introducing a Java
API for RESTful web services (JAX-RS) [JSR 311].

JAX-RS ensures the portability of REST API code across all Java EE-compliant application servers. The latest
version is JAX-RS 2.0 [JSR 339], which was released as part of the Java EE 7 platform.

JAX-RS focuses on applying Java annotations to plain Java objects. JAX-RS has annotations to bind specific URI
patterns and HTTP operations to specific methods of your Java class. It also has annotations that can help you
handle input/output parameters.

As we already said that JAX-RS is a specification; it means we need to have its implementation to run REST API
code. Some of the popular JAX-RS implementations available today are:

Jersey

RESTEasy

Apache CXF

Restlet
2. JAX-RS Annotations
Let’s go through some essential annotations provided by JAX-RS 2.0.

2.1. @Path(‘resourcePath’)
The @Path annotation is used to match the URI path, which is relative to the base URI. It can be specified on
resource class or method.

@Path("/configurations")
public class ConfigurationResource
{
@Path("/{id}")
@GET
public Response getConfigurationById(@PathParam("id") Integer id) {
//…
}
}

The above example sets the path to base URL + /resourcePath. The base URL is based on the application name,
the servlet, and the URL pattern from the web.xml configuration file.

2.2. @POST
The @POST annotated method will handle the HTTP POST requests on the matching resource path.

@POST
@Consumes("application/xml")
public Response createConfiguration(Configuration config) {
//...
}

2.3. @PUT
The @PUT annotated method will handle the HTTP PUT requests on the matching resource path.

@PUT
@Consumes("application/xml")
public Response updateConfiguration(@PathParam("id") Integer id, Configuration config){
//...
}

2.4. @GET
The @GET annotated method will handle the HTTP GET requests on the matching resource path.

@GET
@Path("/{id}")
public Response getConfigurationById(@PathParam("id") Integer id){
//...
}
2.5. @DELETE
The @DELETE annotated method will handle the HTTP DELETE requests on the matching resource path.

@DELETE
@Path("/{id}")
public Response deleteConfiguration(@PathParam("id") Integer id){
//...
}

2.6. @PathParam(“ parameterName” )

The @PathParam is used to inject values (resource identifiers) from the URL into a method parameter.

@DELETE
@Path("/{id}")
public Response deleteConfiguration(@PathParam("id") Integer id){
//...
}

In the above example, the value of id from /{id} will match to @PathParam("id") Integer id.

For example, URI HTTP DELETE /configurations/22312 will be mapped to the above method and id will be
populated with the value 22312.

2.7. @Produces
The @Produces annotation defines which MIME type is delivered by annotated resource methods. It can be
defined at class level as well as method level.

If defined at the class level, all methods inside the resource class will be returning the same MIME type, if not
overridden in any method.

@Path("/configurations")
@Produces("application/xml")
public class ConfigurationResource {
//...
}

2.8. @Consumes
The @Consumes annotation defines which MIME type is consumed by annotated resource method.

@POST
@Consumes("application/xml")
public Response createConfiguration(Configuration config) {
//...
}

2.9. @Context
To build HATEOAS links, JAX-RS 2.0 provides UriInfo class which can be obtained using the @Context annotation.

@Context
UriInfo uriInfo;

By default the JAX-RS runtime will automatically support the methods HEAD and
OPTIONS, if not explicitly implemented.

For HEAD the runtime will invoke the implemented GET method (if present) and ignore
the response entity (if set).

The OPTIONS method can return a response with a set of supported resource methods in
the ‘Allow’ header.

3. Create Maven Application

Maven is a software project management and comprehension tool including project build, reporting, and
documentation from a central piece of information i.e. pom.xml.

To create an application using maven in eclipse, follow these steps:

Open new project wizard from File > New > Maven Project

Create Maven Application – Step 1

Click on the Next button.

 Create Maven Application – Step 2

Select maven-archtype-webapp

Create Maven Application – Step 3

Fill project details and click on Finish

 Create Maven Application – Step 4

4. Include JAX-RS Dependencies

JAX-RS 2.0 comes bundled with JDK 1.7, so if you have JDK 1.7 or higher version in JAVA_HOME then we don’t need
to include JAX-RS separately. However, we will need to include one of its implementations listed above.

In this example, I am using RESTEasy 3.1.2.Final.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instan

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>

resteasy-servlet-initializer artifact enable automatic scanning for resources and

providers in Servlet 3.0 containers.

5. Creating Resource Representations

In JAX-RS, resource representations are POJO classes annotated with JAXB annotations i.e. @XmlRootElement,
@XmlAttribute and @XmlElement etc.

In this example, we are exposing two representations. Let’s create java classes for them.

5.1. Collection Resource of Configurations

package net.restfulapi.app.rest.domain;

import java.util.List;

import javax.ws.rs.core.Link;
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlAttribute;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;

@XmlRootElement(name = "configurations")
@XmlAccessorType(XmlAccessType.FIELD)
public class Configurations
{
 @XmlAttribute
private Integer size;

@XmlJavaTypeAdapter(Link.JaxbAdapter.class)
@XmlElement
private Link link;

@XmlElement
private List<Configuration> configurations;

public Integer getSize() {

return size;
}

public void setSize(Integer size) {

this.size = size;
}

public Link getLink() {

return link;
}

public void setLink(Link link) {

this.link = link;
}

public List<Configuration> getConfigurations() {

return configurations;
}

public void setConfigurations

(List<Configuration> configurations) {
this.configurations = configurations;
}
}

5.2. Singular Configuration resource

package net.restfulapi.app.rest.domain;

import javax.ws.rs.core.Link;
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlAttribute;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;

import net.restfulapi.app.rest.domain.common.Status;

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

@XmlJavaTypeAdapter(Link.JaxbAdapter.class)
 @XmlElement
private Link link;

@XmlElement
private String content;

@XmlElement
private Status status;

public Link getLink() {

return link;
}

public void setLink(Link link) {

this.link = link;
}

public Integer getId() {

return id;
}

public void setId(Integer id) {

this.id = id;
}

public String getContent() {

return content;
}

public void setContent(String content) {

this.content = content;
}

public Status getStatus() {

return status;
}

public void setStatus(Status status) {

this.status = status;
}
}

5.3. Message resource [to inform client when no resource representation

needed]
package net.restfulapi.app.rest.domain.common;

import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name = "message")
public class Message {

public Message() {
super();
}

public Message(String content) {

super();
 this.content = content;
}

private String content;

public String getContent() {

return content;
}

public void setContent(String content) {

this.content = content;
}
}

Additionally, we have simulated the DB functionality using ConfigurationDB class. It exposes static utility methods
for CRUD operations in configuration resource collection and individual configuration resources.

package net.restfulapi.app.dao;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicInteger;

import net.restfulapi.app.rest.domain.Configuration;
import net.restfulapi.app.rest.domain.common.Status;

public class ConfigurationDB

{
private static Map<Integer, Configuration> configurationDB
= new ConcurrentHashMap<Integer, Configuration>();
private static AtomicInteger idCounter = new AtomicInteger();

public static Integer createConfiguration(String content, Status status){

Configuration c = new Configuration();
c.setId(idCounter.incrementAndGet());
c.setContent(content);
c.setStatus(status);
configurationDB.put(c.getId(), c);
return c.getId();
}

public static Configuration getConfiguration(Integer id){

return configurationDB.get(id);
}

public static List<Configuration> getAllConfigurations(){

return new ArrayList<Configuration>(configurationDB.values());
}

public static Configuration removeConfiguration(Integer id){

return configurationDB.remove(id);
}

public static Configuration updateConfiguration(Integer id, Configuration c){

return configurationDB.put(id, c);
 }
}

6. Creating REST Resources

We have already learned about JAX-RS annotations in the second section. Let’s apply them to REST resources
and map HTTP methods on operations on REST resources.

I have added self-explanatory code comments above each method to explain it.

package net.restfulapi.app.rest.service;

import java.util.List;

import javax.ws.rs.Consumes;
import javax.ws.rs.DELETE;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.Link;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.UriBuilder;
import javax.ws.rs.core.UriInfo;

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.Message;
import net.restfulapi.app.rest.domain.common.Status;

/**
* This REST resource has common path "/configurations" and
* represents configurations collection resources
* as well as individual collection resources.
*
* Default MIME type for this resource is "application/XML"
* */
@Path("/configurations")
@Produces("application/xml")
public class ConfigurationResource
{
/**
* Initialize the application with these two default configurations
* */
static {
ConfigurationDB.createConfiguration("Some Content", Status.ACTIVE);
ConfigurationDB.createConfiguration("Some More Content", Status.INACTIVE);
}

/**
* Use uriInfo to get current context path and to build HATEOAS links
* */
@Context
UriInfo uriInfo;

/**
* Get configurations collection resource mapped at path "HTTP GET /configurations"
* */
@GET
public Configurations getConfigurations() {

List<Configuration> list = ConfigurationDB.getAllConfigurations();

Configurations configurations = new Configurations();

configurations.setConfigurations(list);
configurations.setSize(list.size());

//Set link for primary collection

Link link = Link.fromUri(uriInfo.getPath()).rel("uri").build();
configurations.setLink(link);

//Set links in configuration items

for(Configuration c: list){
Link lnk = Link.fromUri(uriInfo.getPath() + "/" + c.getId()).rel("self").build();
c.setLink(lnk);
}
return configurations;
}

/**
* Get individual configuration resource mapped at path "HTTP GET /configurations/{id}"
* */
@GET
@Path("/{id}")
public Response getConfigurationById(@PathParam("id") Integer id){
Configuration config = ConfigurationDB.getConfiguration(id);

if(config == null) {
return Response.status(javax.ws.rs.core.Response.Status.NOT_FOUND)
.build();
}

if(config != null){
UriBuilder builder = UriBuilder.fromResource(ConfigurationResource.class)
.path(ConfigurationResource.class, "getConfigurationById");
Link link = Link.fromUri(builder.build(id))
.rel("self")
.build();
config.setLink(link);
}

return Response.status(javax.ws.rs.core.Response.Status.OK)
.entity(config)
.build();
}

/**
* Create NEW configuration resource in configurations collection resource
* */
@POST
@Consumes("application/xml")
public Response createConfiguration(Configuration config){
if(config.getContent() == null) {
 return Response.status(javax.ws.rs.core.Response.Status.BAD_REQUEST)
.entity(new Message("Config content not found"))
.build();
}

Integer id = ConfigurationDB.createConfiguration(config.getContent(), config.getStatus());

Link lnk = Link.fromUri(uriInfo.getPath() + "/" + id).rel("self")
.build();
return Response.status(javax.ws.rs.core.Response.Status.CREATED)
.location(lnk.getUri())
.build();
}

/**
* Modify EXISTING configuration resource by it’s "id" at path "/configurations/{id}"
* */
@PUT
@Path("/{id}")
@Consumes("application/xml")
public Response updateConfiguration(@PathParam("id") Integer id, Configuration config){

Configuration origConfig = ConfigurationDB.getConfiguration(id);

if(origConfig == null) {
return Response.status(javax.ws.rs.core.Response.Status.NOT_FOUND)
.build();
}

if(config.getContent() == null) {
return Response.status(javax.ws.rs.core.Response.Status.BAD_REQUEST)
.entity(new Message("Config content not found"))
.build();
}

ConfigurationDB.updateConfiguration(id, config);
return Response.status(javax.ws.rs.core.Response.Status.OK)
.entity(new Message("Config Updated Successfully"))
.build();
}

/**
* Delete configuration resource by it’s "id" at path "/configurations/{id}"
* */
@DELETE
@Path("/{id}")
public Response deleteConfiguration(@PathParam("id") Integer id){

Configuration origConfig = ConfigurationDB.getConfiguration(id);

if(origConfig == null) {
return Response.status(javax.ws.rs.core.Response.Status.NOT_FOUND).build();
}

ConfigurationDB.removeConfiguration(id);
return Response.status(javax.ws.rs.core.Response.Status.OK).build();
}
}

7. Register Resources in Runtime

To register JAX-RS REST resource with server’s runtime, you will need to extend javax.ws.rs.core.Application
class and put it in the application’s classpath.

package net.restfulapi.app.rest;

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;
}
}

Here @ApplicationPath annotation identifies this class as REST application to automatic scanning process in
servlet 3.0 containers. It helps in making web.xml file almost empty – with no REST specific configuration at all.

<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
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
<display-name>Archetype Created Web Application</display-name>
</web-app>

8. Demo
Build and deploy this project to any web server and start the server. Now test the REST APIs by invoking the
above URIs on any browser client.

HTTP GET http://localhost:8080/NetworkManagement/network-management/configurations

Fetch collection of configurations.

 HTTP GET – Configuration Collection Resource

HTTP GET http://localhost:8080/NetworkManagement/network-management/configurations/1

Fetch individual configuration.

HTTP GET – Individual Configuration Resource

HTTP POST http://localhost:8080/NetworkManagement/network-management/configurations

Create a new configuration resource.

 HTTP POST – Create New Resource

HTTP PUT http://localhost:8080/NetworkManagement/network-management/configurations/1

Update configuration resource.

HTTP PUT – Update Individual Configuration Resource

HTTP DELETE http://localhost:8080/NetworkManagement/network-management/configurations/1

Remove configuration resource.

 HTTP DELETE – Individual Configuration Resource

Click on the given download link to download the source code for this application.

Download Sourcecode

Was this article helpful?

Let us know if you liked the post. That’s the only way we can improve.

Yes

No

HTTP Status 204 (No Content)

REST API – N+1 Problem

ADVER TISEMENTS