Fuse ESB - Developing RESTful Web Services - Creating responses for common use cases

Creating responses for common use cases

Overview

The Response class provides shortcut methods for handling the more common responses that a RESTful service will need. These methods handle setting the proper headers using either provided values or default values. They also handle populating the entity body when appropriate.

Creating responses for successful requests

When a request is successfully processed the application needs to send a response to acknowledge that the request has been fulfilled. That response may contain an entity.

The most common response when successfully completing a response is OK. An OK response typically contains an entity that corresponds to the request. The Response class has an overloaded ok() method that sets the response status to 200 and adds a supplied entity to the enclosed response builder. There are five versions of the ok() method. The most commonly used variant are:

Response.ok()—creates a response with a status of 200 and an empty entity body.
Response.ok(java.lang.Object entity)—creates a response with a status of 200, stores the supplied object in the responses entity body, and determines the entities media type by introspecting the object.

Example 23 shows an example of creating a response with an OK status.

Example 23. Creating a response with an 200 response

import javax.ws.rs.core.Response;
import demo.jaxrs.server.Customer;
...

Customer customer = new Customer("Jane", 12);

return Response.ok(customer).build();

For cases where the requester is not expecting an entity body, it may be more appropriate to send a 204 No Content status instead of an 200 OK status. The Response.noContent() method will create an appropriate response object.

Example 24 shows an example of creating a response with an 204 status.

Example 24. Creating a response with a 204 status

import javax.ws.rs.core.Response;

return Response.noContent().build();

Creating responses for redirection

The Response class provides methods for handling three of the redirection response statuses.

303 See Other

The 303 See Other status is useful when the requested resource needs to permanently redirect the consumer to a new resource to process the request.

The Response classes seeOther() method creates a response with a 303 status and places the new resource URI in the message's Location field. The seeOther() method takes a single parameter that specifies the new URI as a java.net.URI object.

304 Not Modified

The 304 Not Modified status can be used for different things depending on the nature of the request. It can be used to signify that the requested resource has not changed since a previous GET request. It can also be used to signify that a request to modify the resource did not result in the resource being changed.

The Response classes notModified() methods creates a response with a 304 status and sets the modified date property on the HTTP message. There are three versions of the notModified() method:

notModified();
notModified(javax.ws.rs.core.Entity tag);
notModified(java.lang.String tag);

307 Temporary Redirect

The 307 Temporary Redirect status is useful when the requested resource needs to direct the consumer to a new resource, but wants the consumer to continue using this resource to handle future requests.

The Response classes temporaryRedirect() method creates a response with a 307 status and places the new resource URI in the message's Location field. The temporaryRedirect() method takes a single parameter that specifies the new URI as a java.net.URI object.

Example 25 shows an example of creating a response with an 304 status.

Example 25. Creating a response with a 304 status

import javax.ws.rs.core.Response;

return Response.notModified().build();

Creating responses to signal errors

The Response class provides methods to create responses for two basic processing errors:

serverError()();—creates a response with a status of 500 Internal Server Error.
notAcceptable()(java.util.List<javax.ws.rs.core.Variant> variants);—creates a response with a 406 Not Acceptable status and an entity body containing a list of acceptable resource types.

Example 26 shows an example of creating a response with an 500 status.

Example 26. Creating a response with a 500 status

import javax.ws.rs.core.Response;

return Response.serverError().build();

Comments powered by Disqus