Webservices RESTful com Java no PlayFramework

Webservices RESTful no PlayFramework

O PlayFramework é um framework MVC e para construir webservices nele, primeiro devemos configurar as rotas. As rotas do play são definidas em um arquivo chamado routes, que fica armazenado em um diretório chamado resources. Neste arquivo são definidos os métodos HTTP, o caminho do método chamado e para quais métodos dos controllers serão direcionados estas chamadas. Abaixo é mostrado um exemplo de métodos REST de chamadas a entidade usuário:

GET         /usuario       controllers.UsuarioController.list()
POST       /usuario       controllers.UsuarioController.create()
GET         /usuario/:id  controllers.UsuarioController.get(id:Long)
PUT         /usuario/:id  controllers.UsuarioController.update(id:Long)
DELETE /usuario/:id   controllers.UsuarioController.delete(id:Long)

A definição deste arquivo é bem fácil de ser compreendida. Primeiro definimos os métodos HTTP:

• GET
• POST
• PUT
• DELETE

Na segunda parte do arquivo, é definido o caminho do método.

• /usuario

é acessado ao digitarmos o caminho do servidor, a porta e o caminho do método:
http://localhost:9000/usuario
A terceira parte do arquivo routes, define qual mécontrollers.UsuarioController.list() todo do controller será chamado por aquele caminho http. Nesta definição deve-se utilizar o caminho completo da classe, incluindo o pacote e o nome da classe.

• controllers.UsuarioController.get()

Com isso definimos que o método get da classe controllers.UsuarioController será chamado, quando houver uma chamada GET no caminho /usuario.

Quando o caminho do método contiver algum parâmetro, basta nomear o parâmetro usando o :, que no exemplo acima é o id do usuário. Uma chamada
http://localhost:9000/usuario/123
Irá realizar uma chamada ao método get, convertendo 123 em Long e 123 será usado como argumento do método get.

Definição do controller

A definição do controller é bem simples, só existem duas regras básicas. Primeiro a classe deverá extender a classe abstrata play.mvc.Controller, e todos os seus métodos expostos a chamadas HTTP, deverão retornar um resultado play.mvc.Result. Que nada mais é, que um mapeamento aos status http, por exemplo o ok é um mapeamento ao status HTTP 200 OK.
Abaixo segue um exemplo:

import play.libs.Json;
import play.mvc.Controller;
import play.mvc.Result;

public class UsuarioController extends Controller {   
    public static Result list()

    {
        return ok(Json.toJson(new java.util.ArrayList<Usuario>()));
    }

No exemplo, tem-se a implementação do método list. Repare que no retorno dele, usa-se o método ok, que mapeia o status HTTP 200 para a resposta. E este método irá receber o conteúdo do retorno do método, que neste caso é uma lista de Usuario.
Aqui também é utilizado o objeto Json para converter a lista de usuários em uma string Json.

Definição de métodos com objetos no body

Qualquer método definido no controller pode conter objetos no body, abaixo segue o exemplo do método save, que é um post com um usuário em Json no body:

 public static Result create()
    {
        Usuario newUsuario = Json.fromJson(request().body().asJson(), Usuario.class);
        Usuario inserted = save(newUsuario);
        return created(Json.toJson(inserted));
    }

request().body() retorna o conteúdo do body da chamada, asJson() converte este resultado em json. O método fromJson converte o json no objeto usuário.
Com isso pega-se o resultado json do body da chamada, transforma-o em um objeto json, e converte este json em uma instância do objeto usuário.

Testando:

Os testes do método GET podem ser executados direto no navegador, para isto basta digitar o entereço de execução da sua instância e pronto, por exemplo:

localhost:9000/usuario

Irá executar o método GET do usuário e retornar uma lista de todos os usuários inseridos na sua instância.
Já para testar os outros métodos, devermos ou instalar uma ferramenta de teste de REST, como o SOAPUI ou mesmo instalar uma extensão de REST ao seu navegador, como a RestLet Client.
Para executarmos uma chamada com POST devemos utilizar um json, como o mostrado abaixo:

{ "id": 4, "nome": "DirceuProf", "endereco":{"id": 1, "rua": "Marques de São Vicente", "numero": "3001", "cidade": "Sao Paulo", "estado": "Sao Paulo","cep":"05003000"} }

Lembrando que nos testes você pode, e deve,  alterar os dados que serão inseridos.
Todo o conteúdo de classes deste post está localizado neste repositorio, e apresentação