Introdu��o ao REST WS

Figura 1: Livro sobre web services RESTful

Nos �ltimos tempos, uma forte tend�ncia vem mudando a forma de pensar os Web Services. Ela aponta para uma soluç�o que elimina a complexidade presumida presente nos padr�es dos Web Services convencionais, conhecidos tamb�m como Web Services SOAP ou Web Services WS-* (nomenclatura dada devido usarem diversas tecnologias diferentes). Esta tend�ncia � o REST (REpresentational StateTransfer).

O REST n�o � um padr�o ou uma arquitetura, e sim uma nova forma de se pensar sobre HTTP. Ele � composto por um conjunto de princ�pios e restriç�es que definem como padr�es Web, como HTTP e URIs, podem ser usados. Os defensores do REST acreditam que suas id�ias explicam uma forma mais simples de resolver problemas de integraç�o entre aplicativos e simplificar a estrutura necess�ria para construir arquiteturas orientadas a serviços.

Princ�pios REST

Os princ�pios utilizados por REST permitem que utilizemos a arquitetura da Web a nosso favor. Para REST, qualquer informaç�o dispon�vel � um recurso, por exemplo, um documento, o cadastro de uma pessoa, uma imagem, uma lista de carros. Este � um princ�pio, mas existem outros n�o menos importantes. S�o eles:

Todos os recursos devem ter um identificador;
Hypermedia como m�quina de estado da aplicaç�o;
Interface Uniforme;
Recursos com m�ltiplas representaç�es;
N�o armazenamento de estado (stateless);

Todos os recursos devem ter um identificador

Cada recurso precisa ser identificado unicamente, ou seja, precisa de um "ID". Na Web, a forma de se conseguir um identificador assim � atrav�s de uma URI. A URI permite que se criem namespaces globais, podendo servir como um identificador �nico e global para os recursos. Um recurso pode conter uma informaç�o, como em http://exemplo.com/cliente/12 onde diretamente podemos obter um cliente, ou um conjunto de informaç�es, como em http://exemplo.com/pagamentos/2013/01 onde obtemos os pagamentos realizados em janeiro de 2013. A simplicidade da URI permite ainda, que se mantenha uma sem�ntica que permite visualizar facilmente o recurso.

Hiperm�dia como m�quina de estado da aplicaç�o

Al�m de ser semanticamente coerente, a URI, ou mais precisamente a URL, permite que a hiperm�dia funcione como m�quina de estado da aplicaç�o (das iniciais em ingl�s HATEOAS). Calma, vejamos do que se trata! Parece ser uma coisa de outro mundo ao se julgar pelo nome, por�m esse princ�pio nada mais � do que se utilizar a hiperm�dia (os links) para se acessar um recurso indiretamente, a partir da pr�pria aplicaç�o, sem interfer�ncia humana (sem termos que interagir com os links). E quanto ao estado da aplicaç�o? O estado � alterado ao se seguir o link, ou seja, ao se acessar o outro recurso. Segue um exemplo:

Listagem 1: Exemplo de objeto com links nas propriedades


<venda self='http://exemplo.com/cliente/12' >  
   <quantidade>23</quantidade>  
   <produto ref='http://exemplo.com/produtos/41' />  
   <cliente ref='http://exemplo.com/cliente/12' />  
</venda>

No exemplo, podemos ver que estamos acessando uma venda, por�m, ela permite que ao seguirmos um link, como o de cliente, estamos mudando o estado da aplicaç�o.

Interface Uniforme

A URI ainda permite outras vantagens. Aliada aos m�todos do HTTP, a URI sabe que todos os recursos suportam a mesma interface, o mesmo conjunto de m�todos HTTP. O HTTP possui outros verbos, al�m dos conhecidos GET e POST, s�o eles: PUT, DELETE, HEAD e OPTIONS. Esses m�todos permitem que se obtenha uma interface uniforme, associa estes verbos a necessidades de aplicativo de neg�cios padr�o, mais conhecido por CRUD (do ingl�s Create, Retrieve, Update, Delete), ou seja, armazenamento, busca, atualizaç�o e deleç�o. A tabela 1 mostra esta associaç�o.

Tarefa do Aplicativo	Verbo HTTP
Create	POST
Read	GET
Update	PUT
Delete	DELETE

Tabela 1: Mapeamento CRUD/HTTP

Ao associar os verbos HTTP, que na realidade s�o solicitaç�es, aos recursos, que agem como nomes, obt�m-se uma sem�ntica conversacional. Por exemplo, pode-se criar uma express�o l�gica de comportamento,�GET�este documento e UPDATE�aquele registro.

Recursos com m�ltiplas representaç�es

Os resources tamb�m podem ser representados em diversos formatos (Media Type). Por exemplo, na internet ou em uma intranet, � normal que se possa obter o cadastro de um cliente em diversos formatos, como html, xml e json.

N�o armazenamento de estado (Stateless)

Existem bons motivos para n�o se manter o estado de comunicaç�o com o servidor. Quando necess�rio, deve-se mant�-lo no cliente. Isto permite alguns benef�cios como: visibilidade, n�o � necess�rio verificar a requisiç�o para determinar sua natureza; fiabilidade, a tarefa de recuperaç�o a falhas parciais se torna f�cil; escalabilidade, n�o necessitando armazenar estados entre as requisiç�es, o servidor pode rapidamente liberar recursos facilitando seu gerenciamento.

A desvantagem � a reduç�o de desempenho na rede devido aumenta os dados repetidos enviados nas requisiç�es, e o controle do servidor sobre a consist�ncia da aplicaç�o � reduzido, j� que todo o estado da aplicaç�o fica no lado cliente.

RESTful no JEE6

Os conceitos de REST j� existem a mais de uma d�cada, por�m somente nos �ltimos anos est�o sendo utilizados com mais frequ�ncia, impulsionados principalmente pela expans�o dos dispositivos m�veis. Devido a ascendente utilizaç�o de REST, a plataforma JEE6 incorporou este conceito por meio da especificaç�o JAX-RS 1.1, baseada em anotaç�es. Esta especificaç�o determina como deve ser implementado um serviço Restful, por�m, n�o o implementa. Para implementar facilmente os Web Services Restful, � necess�rio se utilizar um framework como o RESTeasy, o RESTlet, restfulie ou Jersey.

O foco deste artigo � mostrar as principais anotaç�es desta especificaç�o, e explic�-las, de acordo com os princ�pios REST.

De acordo com a JAX-RS, os recursos Web s�o implementados por classes Java (resource classes). Conforme foi visto, todo recurso Web deve possuir uma URI. A anotaç�o que define este recurso � @Path.

Listagem 2: Exemplo de uso da anotaç�o @Path

@Path("/Cliente")
class ClienteResource{
	//Classe que representa o recurso
}

Para se mapear os m�todos HTTP @GET, @PUT, @POST, @DELETE e @HEAD para m�todos Java, deve-se utilizar tamb�m uma resource class.

Listagem 3: Mapeamento do m�todo GET


@Path("/Cliente")
class ClienteResource{
	@GET
	@Produces(MediaType.TEXT_PLAIN)
	public String getCliente(){
		//implementaç�o
	}
}

A especificaç�o JAX-RS tamb�m permite que se apresente mais de um recurso por classe, a partir de sub-recursos.

Listagem 4: Usando sub-recursos


@Path("/Cliente")
class ClienteResource{
	@GET
	@Produces(MediaType.TEXT_PLAIN)
	public String getStatusCliente(){
		//implementaç�o
	}

	@GET
	@Path("/bonus")
	@Produces(MediaType.TEXT_PLAIN)
	public String getBonusCliente(){
		//implementaç�o	
	}
}

Os sub-recursos s�o representados pelo sufixo da URI, concatenando-se os valores das anotaç�es @Path da classe recurso, com a anotaç�o @Path dos sub-recursos. A partir do exemplo, temos: /Cliente/status e /Cliente/bonus. A anotaç�o @Produces determina o tipo de retorno esperado. MediaType � a representaç�o do recurso, no exemplo � um texto simples (TEXT_PLAIN).

Existe uma grande variedade de representaç�es para os recursos, e diversos m�todos implementados pela especificaç�o JAX-RS.