In JAX RS, differences between returning Response and Bean or Collection of Beans (DTO)

I am working on building a REST api. My question is, when using Jersey, what are the differences between my services building and returning a Response object or returning the the bean or collection. I am only concerned with successful calls, I am throwing appropriate exceptions for errors and exceptional situations.

Here is a example:

@Produces(MediaType.APPLICATION_JSON)
public Response search(FooBean foo){
    List<FooBean> results = bar.search(foo);
    return Response.ok(results).build();
}

vs.

@Produces(MediaType.APPLICATION_JSON)
public List<FooBean> search(FooBean foo){
    List<FooBean> results = bar.search(foo);
    return results;
}

I've seen both examples used, and I'd prefer the second scenario, just to make it easier to recognize the service method. I've examined the responses to both of these methods and they appear to be identical.

Thoughts?

The differences are explained in the JAX-RS specification:

3.3.3 Return Type

Resource methods MAY return void, Response, GenericEntity, or another Java type, these return types are mapped to a response entity body as follows:

void
Results in an empty entity body with a 204 status code.

Response
Results in an entity body mapped from the entity property of the Response with the status code specified by the status property of the Response. A null return value results in a 204 status code. If the status property of the Response is not set: a 200 status code is used for a non-null entity property and a 204 status code is used if the entity property is null.

GenericEntity
Results in an entity body mapped from the Entity property of the GenericEntity. If the return value is not null a 200 status code is used, a null return value results in a 204 status code.

Other
Results in an entity body mapped from the class of the returned instance. If the return value is not null a 200 status code is used, a null return value results in a 204 status code.

Methods that need to provide additional metadata with a response should return an instance of Response, the ResponseBuilder class provides a convenient way to create a Response instance using a builder pattern.

'Regular' beans are mapped over in pretty much the same way as Response is, with the exception that a Response allows you to set additional metadata (response headers, specialized status, specialized content type, etc). As far as which one to use, thats entirely up to you too decide - Response gives you more flexibility, but regular beans are more 'self-documenting'.

There is no diference if you want to return always the response 200 - OK , catching and manipulate all the exceptions that may occur before of after your method return the result, with interceptions or WebApplicationException. So, both of these methods will result the same responses.

The only diference is at specific scenarios, like returning null objects, or creating object, like this example:

@POST
@Consumes("application/json")
public Response post(String content) {
    URI createdUri = ...
    Object createdContent = create(content);
    return Response.created(createdUri).entity(createdContent).build();
}

In this case the return will be 201 - CREATED (With the URI to access the created object)

So, the following method:

@POST
@Consumes("application/json")
public Object post(String content) {
    URI createdUri = ...
    Object createdContent = create(content);
    return createdContent;
}

... will return a response 200 - OK

If you don't care about which response status your client will receive, you can use any of declarations without problem.

Source: Jersey.

My personal of view, if response contains DTO (Bean/Collection of beans), then rest service always must return DTO, but not Response object.

The motivation: early or late, you will be asked to make a usage of rest service easier for clients, by providing rest client api. Usually, you have to extract rest interfaces for it, and implement them with your rest services. These rest interfaces are used by clients of your rest client.

And from a client point of view there is a huge difference between processing DTO and plain Response. In case Response is used, your client is forced:

1. Check response code explicitely to process successfull response
2. Handle errors, by checking codes explicitly
3. Convert body of your response into DTO by himself.

Which means handling Response is very similar to returning error codes in methods, which is considered as a very bad practice. In order to handle errors in one place, exceptions are used (I'm not talking about FP ways of handle errors, which is the best).

So what may you do:

1. In case a request is processed successfully, convert in your rest service data into DTO/Bean and return it.
2. In case if validation failed, or something went wrong, throw an exception in your rest service. Perhaps a default exception mapper is not good for you, so, you'll have to implement your own exception mapper.

So if to think in advance, you should return DTO.

One use-case, when plain Response should be returned - when you export file, for instance. It seems JAX RS does not allow to return InputStream object. Not sure, it has to be checked.

The other use case, was pointed by @Perception, but it is more an exception, than a rule:

Methods that need to provide additional metadata with a response should return an instance of Response, the ResponseBuilder class provides a convenient way to create a Response instance using a builder pattern.

Note: it is a general question for JAX RS, does not depend on exact implementation, like Resteasy or Jersey