JAX-RS Resource Implementation

Guide for creating RESTful resources in Java EE (Jakarta EE) using JAX-RS.

Core Annotations

Example Resource

import jakarta.ws.rs.*;
import jakarta.ws.rs.core.*;

@Path("/users")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class UserResource {

    @GET
    @Path("/{id}")
    public Response getUser(@PathParam("id") String id) {
        // Logic to fetch user
        User user = userService.find(id);
        if (user == null) {
            return Response.status(Response.Status.NOT_FOUND).build();
        }
        return Response.ok(user).build();
    }

    @POST
    public Response createUser(User user, @Context UriInfo uriInfo) {
        // Logic to create user
        String id = userService.save(user);
        UriBuilder builder = uriInfo.getAbsolutePathBuilder();
        builder.path(id);
        return Response.created(builder.build()).entity(user).build();
    }
}

Exception Mapping

Use ExceptionMapper to return clean error responses.

import jakarta.ws.rs.ext.*;
import jakarta.ws.rs.core.*;

@Provider
public class EntityNotFoundMapper implements ExceptionMapper<EntityNotFoundException> {
    @Override
    public Response toResponse(EntityNotFoundException ex) {
        ErrorResponse error = new ErrorResponse("NOT_FOUND", ex.getMessage());
        return Response.status(Response.Status.NOT_FOUND)
            .entity(error)
            .type(MediaType.APPLICATION_JSON)
            .build();
    }
}

JSON Data Mapping

Ensure you have a JSON provider (like Jackson or Yasson) registered. Standard DTO:

public class UserDTO {
    public String id;
    public String name;
    // Getters and setters
}

Best Practices

1. Use Response return type for full control over headers and status codes.
2. Follow RESTful naming conventions (plural for resource paths).
3. Use Transfer Objects (DTOs) instead of exposing entities directly.
4. Implement ExceptionMappers for consistent error structures.
5. Annotate classes with @Produces and @Consumes at the type level to avoid repetition.