Boas práticas - Rest

Pessoal...

Estou trabalhando com alguns projetos utilizando Rest. Montei esse e-mail para enviar à equipe de desenvolvimento e resolvi publicar aqui também.

A ideia é utilizar o conceito de RESTful utilizando as melhores práticas de desenvolvimento. Darei algumas dicas simples que podemos seguir:

1) Não usar verbos nos paths dos Rests:

Você não pode ter um localhost:8080/myapp/rest/deletarProduto e dar um HTTP GET nele.

Tem que ser um localhost:8080/myapp/rest/produto e você dá um HTTP DELETE nele



Tem alguns casos especiais (somarValores, checarSeEmailTemFormatoValido ou algoasism...) que são um pouquinho diferentes.. em outra oportunidade falarei mais sobre isso..


2) Passagem de parâmetros através de queryString do método GET

<URL>?parametro1=valor1&parametro2=valor2

Isso deve ser usado para filtros no HTTP GET de localhost:8080/myapp/rest/produto?apenasAtivos=true

Na implementação, basta utilizar @QueryParam ao invés de @PathParam


3) Sempre retornar um Response (javax.ws.rs.core.Response;)

Nunca retorne uma coleção de entidades ou uma string diretamente... encapsule em um Response para poder passar o HTTP Status adequadamente.

return Response.ok(banners).build();
ou outro Status:
return Response.status(Status.FORBIDDEN).build();


4) Sempre retornar JSON de forma automática:
Basta adicionar a linha abaixo acima do método no Rest:
@Produces(MediaType.APPLICATION_JSON)

Não faça a conversão de objetos para JSON na mão.


5) Atualização parcial:
Existem casos onde você não quer atualizar um registro inteiro, e sim apenas uma propriedade dele, atualizar um status por exemplo.

O @PUT é pra atualização, mas ele é pra atualizar o objeto inteiro.

Para isso existe o @PATCH, mas não sei se ele é padrão, se todos os servidores de aplicação tem.

Uma outra ideia é fazer vários @PUT, fica bacana também:

PUT localhost:8080/myapp/rest/livro/{id}/propriedadeX
PUT localhost:8080/myapp/rest/livro/{id}/propriedadeY

Outra ideia é ter um @PUT pra atualizar o objeto inteiro e um @PUT que recebe um Map com os atributos a serem atualizados e seus novos valores.


6) Não implemente todos os métodos
Não é necessário implementar todos os métodos se eles não serão usados. Por exemplo, se é um objeto só vai ter um @GET não é necessário implementar o @POST, o @PUT e o @DELETE.

No máximo faça o método no Rest que retorna um status de erro informando que não foi implementado.


Mais:
Mais detalhes e para quem quiser estudar mais sobre Rest recomendo o artigo abaixo:
http://www.devmedia.com.br/construindo-uma-restful-api-parte-1/29904
http://www.devmedia.com.br/restful-api-construindo-uma-api-simples-parte-2/30069

Na Supero (empresa que trabalho) temos conta MVP no devmedia, caso você não tenho recomendo fazer, é um investimento muito válido!

Abraços!
Adriano Schmidt