RESTEasy Tutorial for Beginners

RESTEasy is JBOSS-provided implementation of JAX-RS specification (the latest version implements Jakarta-RS) for building REST APIs. RESTEasy is a portable implementation of these specifications which can run in any Servlet container. A tighter integration with the WildFly application server makes the user experience nicer.

1. Bootstrapping a RESTEasy Application

The bootstrapping of a RESTEasy application depends on the environment we are running it in. Let us check its configuration for a WildFly as well as a 3rd-party servlet container, both.

1.1. In WildFly

In WildFly, RESTEasy and the Jakarta RESTful Web Services API are automatically loaded. So if we are already using the Jakarta RESTful Web Services annotations, we do not need to do much to make this work.

If any module is not loaded by default, then we can import using the jboss-deployment-structure.xml. In following example, we are additionally importing the resteasy-jackson2-provider module.

<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="org.jboss.resteasy.resteasy-jackson2-provider" services="import"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

By default, WildFly automatically scans the application classes for the Jakarta-RS annotations and configures them. The easiest way to start is by creating a class that extends jakarta.ws.rs.core.Application and is annotated with @ApplicationPath annotation. The UserService class provides all REST endpoints using the @Path annotation. In this case, a web.xml file is not required.

@ApplicationPath("/rws")
public class RestEasyApplication extends Application
{
    private Set<Class> classes = new HashSet<Class>();

    public RestEasyApplication() {
        classes.add(UserService.class);
    }

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

If the above class does not have the @ApplicationPath annotation then we must define the servlet-mapping element in the web.xml file.

<web-app>

  <servlet>
    <servlet-name>Resteasy</servlet-name>
    <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
    <init-param>
      <param-name>jakarta.ws.rs.Application</param-name>
      <param-value>com.howtodoinjava.RestEasyApplication</param-value>
    </init-param>
  </servlet>

  <servlet-mapping>
    <servlet-name>Resteasy</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>

</web-app>

1.2. In Other Servlet Containers

Start with including the latest version of RESTEasy modules from the Maven repository.

<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-core</artifactId>
  <version>6.2.1.Final</version>
</dependency>
<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-client</artifactId>
  <version>6.2.1.Final</version>
</dependency>
<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-jaxb-provider</artifactId>
  <version>6.2.1.Final</version>
</dependency>

In Servlet 3.0 containers and later, we will need to include the resteasy-servlet-initializer dependency, which includes an implementation of the ServletContainerInitializer interface for containers to use in initializing the RESTEasy application. It will automatically scan the application classes for the resources and providers, and programmatic registration of a servlet.

<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-servlet-initializer</artifactId>
  <version>6.2.1.Final</version>
</dependency>

You will need to include a similar servlet-mapping in older servlet containers as mentioned in the previous section.

2. REST Controller

We can now create the REST APIs as we will in any other application using the Jakarta-RS annotations.

import jakarta.ws.rs.*;
import jakarta.ws.rs.core.Response;
import jakarta.xml.bind.annotation.*;

@Path("/user-management")
public class UserService {

@GET
  @Path("/users")
  @Produces("application/xml")
  public Users getAllUsers() {
    Users users = new Users();
    users.setUsers(UserCache.getUsers());
    return users;
  }

  @GET
  @Path("/users/{id}")
  @Produces("application/xml")
  public User getUserById(@PathParam("id") int id) {
    if (id > UserCache.getUsers().size()) {
      //report error
    }
    return UserCache.getUsers().get(id - 1);
  }
}

3. Demo

When we deploy the above-built application in Tomcat 10 and hit the URL: /resteasy-examples/rws/user-management/users/

This endpoint should return all the users in the system, and we shall receive an XML response.

4. Conclusion

In this RESTEasy tutorial, we learned to bootstrap REST APIs using RESTEasy. We learned to create and deploy the API code in WildFly server as well as other Servlet containers such as Tomcat.

Happy Learning !!

Sourcecode on Github