JAX-RS: Como customizar o status code em uma HTTP Response de uma aplicação REST

Os métodos HTTP mais comuns em uma aplicação REST são GET, POST, PUT e DELETE. O protocolo HTTP e a arquitetura REST especificam que cada método HTTP retorne um determinado código de status (status code) ao cliente sobre o resultado da sua requisição.

A recomendação em uma aplicação REST é que ela retorne um status code que reflita o que aconteceu com a requisição. O caso mais simples é o de uma requisição GET bem sucedida, cujo status code retornado pode ser o 200 (Successful – OK) junto com os dados solicitados na requisição.

E no caso de uma operação com o método PUT? Qual deveria ser o retorno? Em caso de uma operação PUT bem sucedida, o retorno pode ser o status code 201 (Successful – Created).

Este link contém uma lista com os status codes disponíveis no protocolo HTTP.

Aplicações REST em Java podem retornar diferentes códigos de status encapsulando a resposta em um objeto Response. Ao invés de retornar um valor como uma String ou um Integer, o método retorna um objeto Response contendo o código de status e outras informações da resposta. A classe Response permite customizar a resposta. O exemplo de código abaixo ilustra o uso de Response:

        @PUT	
	@Path("/create/{id}")
	public Response create(@PathParam("id") long id) {
		ResponseBuilder responseBuilder;
		try {
			if(id < 1) {
				responseBuilder = Response.status(400); //Cliente error 400 - bad request
				return responseBuilder.build();
			} else {
				responseBuilder = Response.created(new URI("/create/" + id));
				return responseBuilder.build();
			}
		} catch (URISyntaxException e) {			
			responseBuilder = Response.serverError();
			return responseBuilder.build();
		}				
	}

 

O método create() cria um novo recurso, caso a criação seja bem sucedida, retorna um Response com o status code 201 e a URI do novo recurso, essa response é obtida por meio do ResponseBuilder retornado com a chamada ao métoto Response.created(), que retorna um ResponseBuilder específico para este caso. Cada método da classe Response retorna um ResponseBuilder específico para cada situação. O método Response.status(int status) retorna um ResponseBuilder com o status passado pelo parâmetro status.

Para saber como criar um web service RESTful com JAX-RS veja o post Criando um web service RESTful com JAX-RS.