Overview

The default response codes that JAX-RS uses are pretty straightforward. There is pretty much a one-to-one relationship to the behavior described in the HTTP 1.1 Method Definition specification. Let’s examine what the response codes would be for both success and error conditions for the following JAX-RS resource class:

Successful Responses

Successful HTTP response code numbers range from 200 to 399. In our example, for the create() and getCustomer() methods of our CustomerResource class, they will return a response code of 200, “OK,” if the Customer object they are returning is not null.

If the return value is null, a successful response code of 204, “No Content,” is returned. The 204 response is not an error condition. It just tells the client that everything went OK, but that there is no message body to look for in the response.

If the JAX-RS resource method’s return type is void, a response code of 204, “No Content,” is returned. This is the case with our update() and delete() methods.

The HTTP specification is pretty consistent for the PUT, POST, GET, and DELETE methods. If a successful HTTP response contains a message body, 200, “OK,” is the response code. If the response doesn’t contain a message body, 204, “No Content,” must be returned.

Error Responses

Error HTTP response code numbers range from 400 to 599. In our example, if a client mistypes the request URI, for example, to customers, it will result in the server not finding a JAX-RS resource method that can service the request. In this case, a 404, “Not Found,” response code will be sent back to the client.

For our getCustomer() and create() methods, if the client requests a text/html response, the JAX-RS implementation will automatically return a 406, “Not Acceptable,” response code with no response body. This means that JAX-RS has a relative URI path that matches the request, but doesn’t have a JAX-RS resource method that can produce the client’s desired response media type.

The JAX-RS implementation will also return an Allow response header back to the client that contains a list of HTTP methods the URI supports. So, if our client did a GET /customers in our example, the server would send this response back:

The exception to this rule is the HTTP HEAD and OPTIONS methods. If a JAX-RS resource method isn’t available that can service HEAD requests for that particular URI, but there does exist a method that can handle GET, JAX-RS will invoke the GET and return the response from that minus the request body.

If there is no existing method that can handle OPTIONS, the JAX-RS implementation is required to send back some meaningful, automatically generated response along with the Allow header set.

Complex Responses

Sometimes the web service you are writing can’t be implemented using the default request/response behavior inherent in JAX-RS. For the cases in which you need to explicitly control the response sent back to the client, your JAX-RS resource methods can return instances of javax.ws.rs.core.Response:

Response objects cannot be created directly; instead, they are created from javax.ws.rs.core.Response.ResponseBuilder instances returned by one of the static helper methods of Response

The ResponseBuilder class is a factory that is used to create one individual Response instance. You store up state you want to use to create your response and when you’re finished, you have the builder instantiate the Response:

Let’s look at an example of a JAX-RS resource method setting some specific response headers:

Here, our getBook() method is returning a plain-text string that represents a book our client is interested in. We initialize the response body using the Response.ok() method.

The status code of the ResponseBuilder is automatically initialized with 200. Using the ResponseBuilder.language() method, we then set the Content-Language header to French.

We then use the ResponseBuilder.header() method to set a custom response header. Finally, we create and return the Response object using the ResponseBuilder.build() method.

One interesting thing to note about this code is that we never set the Content-Type of the response. Because we have already specified an @Produces annotation, the JAX-RS runtime will set the media type of the response for us.

That’s all for Response Codes in RESTful Service. Happy Learning!!

2 Thoughts on “Default Response Codes in RESTful Web Services”

Leave a Reply

Your email address will not be published. Required fields are marked *