Jax-rs — How to return JSON and HTTP status code together?

Creating and serving JSON responses

To create a response that whips up a JSON meal, annotate your JAX-RS method with @Produces("application/json"). This signs a pact with your clients, promising a JSON response. Like a chef showing off his signature dish's ingredients:

@GET
@Produces("application/json")
public Response makeJson() {
    MySpecialObject jsonObj = new MySpecialObject();
    return Response.ok(jsonObj).build(); // Piping hot JSON, coming up with 200 on the side!
}


Serving up custom HTTP status codes

When you're cooking up responses, add a dash of HTTP status code by enlisting the help of Response.Status enumeration or directly. For a 201 Created status hot off the stovetop with a JSON payload, it's as simple as:

return Response
    .status(Response.Status.CREATED) // Code 201, freshly minted!
    .entity(jsonEntity)
    .build();


Exception handling with customized error attainments

Use ExceptionMapper as your sous chef for dealing with exceptions and precision-cut error responses. It is essential when you want to serve your clients more mouth-watering error messages:

@Provider
public class MyExceptionMapper implements ExceptionMapper<MyException> {
    @Override
    public Response toResponse(MyException excep) {
        return Response
                .status(Response.Status.BAD_REQUEST)
                .entity(new ErrorMessage(excep.getMessage())) // A meal of an error message to savor
                .build();
    }
}


Utilizing Response Builder for a delicious experience

The Response builder provides a smorgasbord of methods for crafting the perfect HTTP response. For instance, set the Location header and add custom headers when serving a 201 Created:

return Response
    .created(new URI("http://wonderchef.com/myrecipe"))
    .header("X-Custom-Header", "A pinch of salt")
    .entity(jsonEntity)
    .build();


Handling null and empty ingredients

Brace your endpoints against null or empty input to fend off unexpected crashes in your kitchen. Either serve a fallback or default meal, or hand out an appropriate HTTP error status dish:

if(input == null || input.trim().isEmpty()) {
    return Response
            .status(Response.Status.BAD_REQUEST)   // Uh oh! We got a bad order, folks!
            .entity("Empty orders not accepted!")
            .build();
}


Client-side enthusiasts of your dishes of responses

Your status code creations are the aromatic fragrances that entice client-side JavaScript to perform conditional operations. It's like a foodie excitedly talking about your meal:

if (response.status === 200) {
    console.log('Ah, success:', response.payload);
} else {
    console.error('Disaster:', response.statusText);
}


Chefs' secret techniques for advanced response crafting

Stepping beyond the essential use of Response, a master chef employs ingredients like creating custom annotations and filters using ContainerResponseFilter for automatic response behaviour and pristine code separation.

Curation of custom response filters

For best results, seasoned chefs recommend using custom annotations in union with ContainerResponseFilter. This method ensures the proper HTTP status codes are assigned without overcrowding your main dish.

Here's a sweet example of an annotation:

@NameBinding
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface CustomStatus {
    Response.Status value() default Response.Status.OK;
}


And its filter partner-in-crime:

@Provider
@CustomStatus
public class CustomStatusFilter implements ContainerResponseFilter {
    @Override
    public void filter(ContainerRequestContext requestContext, ContainerResponseContext responseContext) {
        CustomStatus annotation = findAnnotation(requestContext); // Playing hide-n-seek with annotations!
        if (annotation != null) {
            responseContext.setStatus(annotation.value().getStatusCode());
        }
    }
}


Navigating URL parameters with finesse

Should your endpoint request URL parameters, use @PathParam to elegantly serve them. You're crafting a responsive meal that truly complements the client's request:

@GET
@Path("/{id}")
@Produces("application/json")
public Response getRecord(@PathParam("id") String id) {
    MyObject jsonEntity = seekEntityById(id);
    if (jsonEntity == null) {
        return Response.status(Response.Status.NOT_FOUND).build(); // Always disappointing to be out of their favorite dish…
    }
    return Response.ok(jsonEntity).build(); // All good; their order is up!
}


Crafting eloquent error messages

A master chef ensures that their delectable creations leave an impression. This principle applies to error messages too. Pair them with HTTP status codes for maximum impact, adding a flair of professionalism to your service:

return Response
    .status(Response.Status.INTERNAL_SERVER_ERROR)
    .entity(new ApiError("I think I left the oven on!", e.toString())) // Always stay calm in the face of disaster
    .build();


A well-cooked error like ApiError delivers consistent error responses, making error handling easier for your clients.

Catering to client-side expectations

Delighting clients always involve catering to their needs. Be mindful of how browsers or proxies decipher your HTTP status codes. For instance, 204 No Content or 205 Reset Content can trigger some unintended client-side antics. Stay true to your API contract for a smoother service!