Skip to content

RestEasy

Web & HTTPWebJava
Official docs ↗GitHub ↗

What it is

RestEasy is a JAX-RS implementation for building RESTful web services in Java. It provides tools to create REST APIs easily with annotations, dependency injection, exception handling, and integrates well with JBoss/WildFly or standalone servlet containers.

RestEasy allows developers to define REST endpoints using JAX-RS annotations like @Path, @GET, @POST, @PUT, @DELETE, and supports JSON/XML serialization, request/response filters, exception mapping, and asynchronous endpoints. It also provides a client API for consuming REST services programmatically.

Installation

Add the following dependency in pom.xml: <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-jaxrs</artifactId> <version>6.2.4.Final</version> </dependency>

Getting started

The smallest useful thing you can do with it, and what each part means.

Simple GET endpoint
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/hello")
public class HelloResource {
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello RestEasy!";
    }
}
Defines a basic GET endpoint at `/hello` that returns a plain text response.
POST endpoint with JSON input
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/users")
public class UserResource {
    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public User createUser(User user) {
        // Process and return user
        return user;
    }
}
Defines a POST endpoint that accepts a JSON object, processes it, and returns a JSON response.

Advanced usage

Where the library earns its place over a simpler alternative.

Exception Mapper
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;
import jakarta.ws.rs.core.Response;

@Provider
public class GenericExceptionMapper implements ExceptionMapper<Exception> {
    @Override
    public Response toResponse(Exception exception) {
        return Response.status(Response.Status.INTERNAL_SERVER_ERROR)
                       .entity(exception.getMessage())
                       .build();
    }
}
Maps exceptions globally and returns a structured HTTP response.
Request/Response Filter
import jakarta.ws.rs.container.ContainerRequestContext;
import jakarta.ws.rs.container.ContainerRequestFilter;
import jakarta.ws.rs.ext.Provider;

@Provider
public class LoggingFilter implements ContainerRequestFilter {
    @Override
    public void filter(ContainerRequestContext requestContext) {
        System.out.println("Incoming request: " + requestContext.getUriInfo().getRequestUri());
    }
}
Implements a request filter that logs incoming requests.
Asynchronous Endpoint
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.container.AsyncResponse;
import jakarta.ws.rs.container.Suspended;
import java.util.concurrent.CompletableFuture;

@Path("/async")
public class AsyncResource {
    @GET
    public void asyncHello(@Suspended AsyncResponse response) {
        CompletableFuture.supplyAsync(() -> "Hello Async RestEasy!")
                         .thenAccept(response::resume);
    }
}
Demonstrates asynchronous request processing using @Suspended AsyncResponse.
Client API Example
import org.jboss.resteasy.client.jaxrs.ResteasyClient;
import org.jboss.resteasy.client.jaxrs.ResteasyClientBuilder;
import org.jboss.resteasy.client.jaxrs.ResteasyWebTarget;

ResteasyClient client = new ResteasyClientBuilder().build();
ResteasyWebTarget target = client.target("http://localhost:8080/hello");
String response = target.request().get(String.class);
System.out.println(response);
Shows how to use RestEasy client to send a GET request to a REST service.

Errors and fixes

The failures you are most likely to hit, and what actually resolves them.

NotFoundException
Thrown when a requested resource path does not exist. Ensure correct @Path mappings.
BadRequestException
Thrown when the client sends invalid data (HTTP 400). Validate input properly.
ProcessingException
Occurs during client-side API calls, often due to network issues or misconfigured requests.

Best practices

  • Organize resource classes, DTOs, and services for maintainable code structure.
  • Use ExceptionMappers for consistent error handling.
  • Use Filters and Interceptors for cross-cutting concerns like logging, authentication, and metrics.
  • Leverage CDI for dependency injection and modular design.
  • Document your endpoints clearly using OpenAPI or Swagger integration.

Background

Why it exists, and what it was reacting to.

RestEasy was developed by JBoss to provide a lightweight, flexible, and robust REST framework for Java applications. It fully implements the JAX-RS specification and offers extensions for client and server APIs, asynchronous processing, filters, interceptors, and integration with CDI and EJB. RestEasy is widely used in enterprise Java applications, microservices, and projects requiring high-performance REST APIs.

Related libraries

Others in Web & HTTP for Java.

← All Java librariesJava guide