Prática da Disciplina de Sistemas Distribuídos Web ...dai.ifma.edu.br/~mlcsilva/aulas_sisdistribuidos/PráticaWSREST.pdf · Existe uma certa confusão quanto aos termos REST e RESTful

INSTITUTO FEDERAL DE EDUCAÇÃO, CIÊNCIA E TECNOLOGIA DO MARANHÃO

CAMPUS SÃO LUÍS – MONTE CASTELO

DIRETORIA DE ENSINO SUPERIOR

DEPARTAMENTO ACADÊMICO DE INFORMÁTICA

1

Prática da Disciplina de Sistemas Distribuídos – Web Services REST

IFMA – DAI – Professor Mauro Lopes C. Silva

1. O que é REST e 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).

Figura 1: REST x SOAP

fonte: http://dret.net/netdret/docs/soa-rest-www2009/rest-ws.pdf

REST significa Representational State Transfer. Em português, Transferência de Estado Representacional. Trata-se de

uma abstração da arquitetura da Web. Resumidamente, o REST consiste em princípios/regras/constraints que, quando

seguidas, permitem a criação de um projeto com interfaces bem definidas. Desta forma, permitindo, por exemplo,

que aplicações se comuniquem.

Existe uma certa confusão quanto aos termos REST e RESTful. Entretanto, ambos representam os mesmos princípios.

A diferença é apenas gramatical. Em outras palavras, sistemas que utilizam os princípios REST são chamados de

RESTful.

• REST: conjunto de princípios de arquitetura

• RESTful: capacidade de determinado sistema aplicar os princípios de REST.

2. 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;





2

• 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.

Tabela 1: Mapeamento CRUD/HTTP





3

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.

2. JAX-RS (Java API for RESTful Web Services)

Os web services podem ser implementados de muitas maneiras diferentes, cada uma com vantagens e desvantagens

próprias da solução técnica adotada. Em sistemas desenvolvidos utilizando-se a linguagem Java existem duas soluções,

que na documentação da Oracle; são denominadas como Big Web Services e RESTful Web Services. Tanto os web

services Big quanto os RESTful fazem parte da API Java para XML (Java API for XML — JAX), que foi introduzida ao Java

SE na versão 5.

A solução denominada Big Web Services é baseada na troca de mensagens codificadas em XML e utiliza o Protocolo

de Acesso Simples a Objetos (Simple Object Access Protocol — SOAP), cujo padrão é mantido pela W3C.

Já os web services RESTful (Representational State Transfer) são mais adequados para a utilização em cenários mais

básicos, e também são melhor adaptados ao uso do protocolo HTTP do que os serviços SOAP. Os serviços RESTful são

mais leves, o que significa que podem ser desenvolvidos com menor esforço, tornando-os mais fáceis de serem

adotados como parte da implementação de um sistema.

Devido a ascendente utilização de REST, a plataforma Java 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. Em nosso caso, usaremos um servidor de aplicações que já implementa

internamente o RESTeasy.

Para que o servidor de aplicações possa prover serviços RESTful, além da implementação do próprio serviço, é

necessário também que esteja disponível a implementação da API JAX-RS, na qual estão disponíveis os serviços e as

classes que definem as anotações e os seus correspondentes comportamentos, tornando possível a ligação entre as

solicitações dos clientes e os recursos do web service publicado. A implementação de referência da API JAX-RS é o





4

Jersey, um projeto de código aberto, portável, com qualidade, que está agora em sua versão 2.23 e que contempla as

JSRs 311 e 339, que dizem respeito aos web services RESTful.

3. Anotações JAX-RS

O padrão RESTful faz uso de anotações para facilitar o desenvolvimento dos web services, de modo que a declaração

dos recursos e ações que poderão ser realizadas sejam especificadas utilizando esses metadados nos membros da

classe. Algumas das anotações mais utilizadas, definidas pela API JAX-RS, estão listadas abaixo, juntamente com uma

breve explicação a respeito do seu significado e de como são inseridas no código.

@Path Informa o valor de uma URI relativa, que determina o caminho no qual a classe ou método será hospedado no servidor.

Além da especificação do caminho do recurso é possível também incluir a definição de variáveis nas URIs, como o

nome do usuário manuseando o sistema ou os parâmetros a serem utilizados durante a execução da requisição

enviada pelo cliente.

@GET Essa anotação é um designador de método de pedido (Request Method Designator), que corresponde ao método HTTP

de mesmo nome, e determina que o método da classe anotado processe e responda às solicitações GET recebidas. O

resultado esperado é que o serviço retorne o valor correspondente ao recurso solicitado, que pode ser o conteúdo de

um atributo, os registros de uma tabela em uma base de dados, o resultado de algum cálculo, entre outras

possibilidades.

@POST Essa anotação também é um designador de método de pedido e determina que o método da classe anotado processe

e responda às solicitações POST recebidas. Como resultado de uma requisição POST é esperada a alteração do valor

ou estado de algum recurso disponibilizado pelo serviço, que pode ser um registro em uma base de dados, o conteúdo

de um arquivo, entre outros.

@PUT Essa anotação também é um designador de método de pedido e determina que o método da classe anotado processe

e responda às solicitações PUT recebidas. O uso de uma requisição PUT objetiva a criação de um recurso pelo serviço,

que pode ser um arquivo, um registro em um arquivo ou em uma base de dados, entre tantas outras situações

possíveis.

@DELETE Esta anotação também é um designador de método de pedido e determina que o método da classe anotado processe

e responda às solicitações DELETE recebidas. O resultado esperado para uma requisição DELETE é a eliminação ou

destruição do recurso correspondente, ou seja, corresponde à eliminação do conteúdo de um registro em uma base

de dados ou à remoção de um arquivo de dados, conforme a especificação utilizada na implementação do serviço.

@PathParam Essa anotação designa um parâmetro que está na URI de requisição do serviço. O nome e posição dos parâmetros na

URI são determinados pelo modelo definido pela anotação @Path.

@QueryParam





5

Essa anotação designa um parâmetro que está na parte de parâmetros de busca da URI enviada pelo cliente. Os

parâmetros definidos dessa forma não necessitam estar especificados no modelo da URI definido pela anotação

@Path.

@Consumes É uma anotação para especificar o tipo de dado que um recurso pode consumir, ou seja, que o cliente pode enviar ao

serviço. Os tipos de dados dessa anotação são especificados usando-se os tipos do padrão MIME.

@Produces Essa é uma anotação para especificar o tipo de dados que um recurso pode produzir e enviar para o cliente em resposta

a uma solicitação. Os tipos de dados dessa anotação também são especificados usando-se os tipos do padrão MIME.

4. Criando um Web Service REST usando WildFly 10 e o JBoss Tools

Para criar nosso Web Service REST iremos usar as mesmas ferramentas que usamos na prática de Web Services SOAP:

• Eclipse Luna JEE (no meu caso estou usando o Orion)

• WildFly 10 (Uma alternativa a quem tiver problemas com o WildFly 10 é o GlassFish)

• JBoss Tools

4.1 Contexto da Aplicação

Iremos nesta prática desenvolver um serviço REST para uma empresa chamada BoaMúscia. Esta empresa possui várias

rádios espalhadas pelo Brasil. Um dos programas mais esperados pelos ouvintes é o Top10, um programa que toca as

10 músicas mais pedidas durante um determinado mês. Geralmente a lista envolve vários tipos de artistas e estilos

bem diferentes. Uma empresa chamada SóCDLegal, sabendo da audiência do programa Top10 resolve lançar CDs com

as músicas mais tocadas em cada Rádio da empresa BoaMúsica. Assim a empresa SóCDLegal necessita todo mês da

lista Top10 de cada rádio da empresa BoaMúsica. A empresa BoaMúsica possui uma aplicação desenvolvida em C#

que gerencia os dados relacionados ao Top10 de cada rádio. A Figura 2 apresenta a Tela de Cadastro de Rádios desta

aplicação. E a Figura 3 apresenta a Tela que monta o Top10 de uma determinada rádio.

Figura 2: Tela de Cadastro de Rádios fonte: próprio autor





6

Na Figura 3 podemos perceber que a tela para manutenção dos Top10 é um pouco mais complexa que a de Cadastro

de Rádios, pois seu uso envolve a definição de vários elementos (artista, música, posição, etc).

Figura 3: Tela de Cadastro de Top10 fonte: próprio autor

Um novo grupo de Profissionais de TI foi contratado pela Empresa BoaMúsica, e esta equipe propõe uma solução

baseada em REST que fará com que a lista de Top10 salva pelas Rádios da Empresa BoaMúsica, sejam

automaticamente disponibilizadas para a empresa SóCDLegal. A equipe é especializada em Java e propõe que seja esta

a tecnologia utilizada para implementação do serviço REST. A proposta é apresentada ao segmento de negócios da

BoaMúsica e ela concorda com a proposta do pessoal de TI.

4.2 Aplicação Provedora de Serviços REST

Para a prática devem ser seguidos os seguintes passos para a criação da aplicação Provedora de Serviços.

1. Fazer download do arquivo WAR1 disponibilizado no site da disciplina (Aplicação Radio Web Service);

2. Fazer download do Modelo de Dados da aplicação (Modelo de Dados da Aplicação Radio Web Service);

3. Fazer download do arquivo de carga de dados para a base de dados.

Aplicação Radio Web Service Ao fazer download do arquivo WAR2 da aplicação, este deverá ser importado para dentro do Eclipse. Após fazer o

import, você terá em seu workspace a seguinte estrutura de projeto, de acordo com a Figura 4.

1 WAR: Um arquivo WAR é um arquivo JAR (Java ARchive) salvo com uma extensão diferente. Arquivos deste tipo possuem dentro dele, normalmente, toda a estrutura e arquivos relacionados a uma aplicação web desenvolvida em Java.





7

Figura 4: Estrutura do Projeto RadioWebService fonte: próprio autor

Nela temos os pacotes:

dao: pacote contendo as classes de acesso e manipulação do banco de dados. Neste pacote temos duas classes:

DAORadio e DAOTOP10. Cada uma responsável por manipular respectivamente as tabelas Radio e Top10. Estas

tabelas serão apresentadas na seção de modelo de dados;

modelo: pacote contendo as classes que representam as entidades contidas no banco de dados. Neste pacote temos

duas classes: Radio e Top10 que representam respectivamente as duas tabelas contidas em nossa base de dados.

util: pacote contendo a classe GerenciaBD, responsável por criar as conexões com o banco de dados. Esta classe

funciona semelhante a uma fábrica de conexões e é usada nas classes DAO. Há também neste pacote uma classe

chamada Teste.java. Esta classe é uma Java Application, criada para que possamos testar o funcionamento da

estrutura criada.

Modelo de Dados da Aplicação Radio Web Service

A Figura 5 apresenta o modelo de dados da aplicação. Neste modelo temos duas entidades: Radio e Top10. A tabela

Radio persiste as rádios pertencentes a empresa BoaMúsica. E a tabela Top10 persiste a lista de músicas por mês

pertencentes ao top10 de cada rádio.





8

Figura 5: Modelo de Dados da Aplicação Radio Web Service

fonte: próprio autor

Para que a aplicação Provedora REST possa ser desenvolvida é necessário que seja criado o banco de dados baseado

neste modelo. Em nossa página disponibilizamos o modelo de dados, que após ser baixado deverá ser aberto na

ferramenta MySqlWorkbench (de preferência). Através do MySqlWorkbench podemos realizar um “forward

engineer” (opção disponível no menu Database), que transforma o modelo aberto em uma base de dados. Em nossa

página também foi disponibilizado um arquivo (cargaSQLRadioWebService.txt) que possui uma série de INSERTs que

promovem a carga na base de dados com algumas rádios e um Top10 de uma rádio. Realizados todos estes passos,

podemos então desenvolver a nossa aplicação provedora de serviços REST.

Implementação da Aplicação Provedora de Serviços REST

Após a criação do nosso projeto, vamos seguir os seguintes passos:

1. Criar um pacote denominado recursos;

2. Neste pacote iremos criar uma classe que implementa o nosso serviço REST, denominada RadioWebServices

(Figura 6);

3. Copiar para a pasta recursos a classe disponibilizada em nossa página, denominada ApplicationConfig.java.

Esta classe terá papel fundamental na configuração dos nossos serviços REST junto ao servidor de aplicações

WildFly.

Implementação da classe RadioWebServices

A primeira ação de implementação desta classe é a criação de um método que informado um id de uma Rádio como parâmetro ele realize a busca na base de dados, preencha um objeto com os dados da referida entidade e retorne este objeto. Esta ação foi implementada por um método denominado retornaRadioporId(). A Figura 6 apresenta a implementação da classe RadioWebServices.





9

Figura 6: Implementação da classe RadioWebServices – método retornaRadioporId() fonte: próprio autor

Observando a Figura 6, podemos perceber a simplicidade do método retornaRadioporId(). Ele faz uso da classe DAORadio. A classe DAORadio já possui em sua implementação um método que realiza exatamente o que queremos. Outra observação ou até mesmo um questionamento que pode ser feito é: A classe RadioWebServices é uma classe Java comum, como pode ela representar um Provedor de Serviços REST? Bem, a resposta é simples: Iremos transformar esta classe Java comum em um Provedor de Serviços REST incluído nela as anotações JAX-RS apresentadas anteriormente. A Figura 7 apresenta a mesma classe RadioWebServices, porém com as anotações JAX-RS que transformam esta classe em um Provedor de Serviços REST.

Figura 7: Implementação da classe RadioWebServices com as anotações JAX-RS

fonte: próprio autor Alguns pontos a serem explanados:





10

• Da linha 3 a linha 7 são feitos os imports das diversas classes que são usadas na implementação de um serviço REST usando Java (JAX-RS). Temos de ter cuidado com estes imports pois há várias APIs disponibilizadas junto ao Eclipse que possuem classes com estes mesmos nomes (Path, PathParam, etc). Todos os nossos imports tem como raiz: “javax.ws.rs”;

• Na linha 12 temos a definição do nosso recurso através da anotação @Path aplicada a classe. Na verdade, temos a estruturação do caminho que será usado para se chegar aos serviços disponibilizados junto a este recurso.

• Na linha 15 temos a anotação que informa qual verbo HTTP este nosso serviço será associado. Como o serviço recupera um recurso (Radio), iremos usar a anotação @GET.

• Na linha 16 temos a definição do nosso subrecurso através da anotação @Path, só que desta vez aplicada ao método. Na verdade, temos a estruturação do caminho que será usado para se chegar ao serviço disponibilizado por este método.

• Na linha 17, devido a este serviço retornar um recurso, precisamos informar em que formato de dados este recurso será retornado. Para tal finalidade, usamos a anotação @Produces em conjunto com o ENUM MediaType para definir o nosso retorno de objeto Radio em formato JSON.

• Na linha 18 fazemos uso da anotação @PathParam, para indicar à URL do recurso que estamos construindo, que teremos um parâmetro e este possui um nome, id. Perceba que no @Path(“radio/{id}”), este {id} é o mesmo id que esta indicado na anotação @PathParam, ou seja, eles devem ter o mesmo nome.

Utilização da classe ApplicationConfig.java Após a criação do nosso serviço REST, precisamos registrá-lo junto ao nosso servidor de aplicação WildFly. Para realizar este registro (deploy), faremos uso da classe ApplicationConfig.java. A Figura 8 apresenta esta classe do jeito que a mesma foi obtida na página da disciplina.

Figura 8: Implementação da classe ApplicationConfig.java fonte: próprio autor





11

Para fazermos uso desta classe, que nos auxiliará no processo de fazer o deploy do nosso web services REST, devemos realizar algumas alterações. A classe em si, tem um código padrão e que desta forma o aluno não precisa se preocupar com a sua implementação, fazendo apenas as alterações apontadas aqui. A 1ª alteração é a mudança do nome do pacote a qual a classe estará sendo copiada (linha 1). Mudaremos o nome do pacote de “nossoservico” para “recursos”. A 2ª alteração é a modificação do conteúdo da anotação @ApplicationPath (linha 9). Este conteúdo fará parte da composição da URL dos serviços gerenciados por esta aplicação. Na classe o conteúdo é “webservices”, alteraremos ele para “boamusicaservice”. A terceira alteração e mais importante, iremos alterar na linha 24 o argumento da chamada resources.add() para o nome da nossa classe que implementa o nosso Provedor de Serviços REST. E caso você venha a ter mais classes Provedores de Serviços REST, para fazer o deploy delas, basta adicionar resources.add() a este método passando como argumento o nome da classe que implementa o Provedor de Serviços. A Figura 9 apresenta a classe ApplicationConfig.java após as modificações.

Figura 9: Implementação da classe ApplicationConfig.java após as modificações

fonte: próprio autor Realizando o deploy da Aplicação RadioWebService junto ao Wildfly Após a atualização do arquivo ApplicationConfig.java com as orientações anteriores, podemos de forma simples realizar o deploy do nosso web services REST. Ative o Servidor de Aplicações Wildfly. Após o mesmo estar rodando, arraste o seu projeto para ele. Pronto o deploy será realizado. A partir deste momento temos um serviço REST rodando na seguinte URL: http://localhost:8080/RadioWebService/boamusicaservice/radioservice/radio/1 Em que: RadioWebService: é o nome do nosso Dynamic Web Project; boamusicaservice: é o valor do nosso @ApplicationPath contido na classe ApplicafioConfig.java; radioservice: é o valor do @Path anotado na definição da classe RadioWebServices; radio: é o valor do @Path anotado no método da classe RadioWebServices; 1: é o argumento a ser passado para o serviço. Ele é o id do @Path(“radio/{id}”) anotado no método. A Figura 10 apresenta o resultado da chamada realizada ao nosso serviço.

http://localhost:8080/RadioWebService/boamusicaservice/radioservice/radio/1





12

Figura 10: Resultado de uma chamada ao nosso serviço

fonte: próprio autor

5. Conclusão Demonstramos aqui em passos simples como criamos um Web Services REST usando a API disponibilizada pelo JAX-RS. Esperamos que os alunos possam reproduzir estes passos e possam compreender a forma como o Java trabalha com a implementação de Web Services. Para completar esta prática o aluno deverá implementar o serviço solicitado pela empresa SóCDLegal.

Referências

https://www.devmedia.com.br/introducao-a-web-services-restful/37387

https://www.devmedia.com.br/introducao-ao-rest-ws/26964

https://becode.com.br/o-que-e-api-rest-e-restful/

https://www.infoq.com/br/articles/rest-introduction

https://www.devmedia.com.br/introducao-a-web-services-restful/37387

https://www.devmedia.com.br/introducao-ao-rest-ws/26964

https://becode.com.br/o-que-e-api-rest-e-restful/

https://www.infoq.com/br/articles/rest-introduction

Documents

Prática da Disciplina de Sistemas Distribuídos Web ...dai.ifma.edu.br/~mlcsilva/aulas_sisdistribuidos/PráticaWSREST.pdf · Existe uma certa confusão quanto aos termos REST e RESTful