Complete Guide to Returning JSON and HTTP Status Codes Together in JAX-RS

Overview of JAX-RS Response Mechanism

In the JAX-RS framework, returning JSON data while specifying HTTP status codes is a common requirement. The traditional approach of directly returning entity objects only provides the default 200 status code. For finer control over HTTP responses, we need to utilize the javax.ws.rs.core.Response class.

Core Usage of Response Class

The Response class provides comprehensive capabilities for building HTTP responses. Through its static factory methods and builder pattern, we can create complete responses containing status codes, entity content, and media types.

@GET
@Path("retrieve/{uuid}")
public Response retrieveSomething(@PathParam("uuid") String uuid) {
    if(uuid == null || uuid.trim().length() == 0) {
        return Response.serverError().entity("UUID cannot be blank").build();
    }
    Entity entity = service.getById(uuid);
    if(entity == null) {
        return Response.status(Response.Status.NOT_FOUND).entity("Entity not found for UUID: " + uuid).build();
    }
    String json = //convert entity to json
    return Response.ok(json, MediaType.APPLICATION_JSON).build();
}

Error Status Code Handling

For error scenarios, JAX-RS provides multiple handling approaches. Beyond directly using Response builders, predefined exception types like BadRequestException, InternalServerErrorException, and NotFoundException can be thrown. These exceptions automatically map to corresponding HTTP status codes.

Success Status Codes and Automatic Serialization

In success scenarios, non-200 status codes are sometimes required, such as 201 Created when creating resources. When using JAXB automatic serialization, serialization functionality can be preserved through Response builders:

@Path("/")
@POST
@Consumes({ MediaType.APPLICATION_JSON })
@Produces({ MediaType.APPLICATION_JSON })
public Response addUser(User user) {
    User newUser = ...
    return Response.created(hateoas.buildLinkUri(newUser, "entity")).entity(newUser).build();
}

Content Negotiation

JAX-RS supports content negotiation, allowing clients to specify desired response formats through Accept headers. Servers can declare supported media types using the @Produces annotation, and the framework automatically selects the most appropriate format for response.

Exception Mapping Mechanism

For custom business exceptions, unified handling can be achieved by implementing the ExceptionMapper interface:

@Provider
public class MyApplicationExceptionHandler implements ExceptionMapper<MyApplicationException> {
    @Override
    public Response toResponse(MyApplicationException exception) {
        return Response.status(Status.BAD_REQUEST).entity(exception.getMessage()).build();
    }
}

Performance Optimization Considerations

In modern frameworks like Quarkus REST, response processing can fully leverage reactive programming models. By returning Uni or Multi types, non-blocking IO operations can be implemented, significantly improving system throughput.

Best Practices Summary

In practical development, it's recommended to uniformly use the Response class for handling all HTTP responses, maintaining code consistency and maintainability. Meanwhile, properly utilizing exception mapping mechanisms can decouple business logic from HTTP protocol details, resulting in clearer code.