// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= Introdução aos Web Services RESTful
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: Introdução aos Web Services RESTful - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, Introdução aos Web Services RESTful

REST (REpresentational State Transfer) é um estilo de arquitetura para sistemas de hipermídia distribuídos, como a World Wide Web. O conceito dos recursos identificados por identificadores de recursos universais (URIs) é central para a arquitetura RESTful. Esses recursos podem ser manipulados usando uma interface padrão, como HTTP, e as informações são trocadas usando representações desses recursos. Neste tutorial, você primeiro aprende um pouco sobre REST e depois vê como o NetBeans IDE dá suporte a esse estilo de arquitetura.


image::images/netbeans-stamp-80-74-73.png[title="O conteúdo desta página se aplica ao NetBeans IDE 7.2, 7.3, 7.4 e 8.0"]


*Para seguir este tutorial, são necessários os recursos e o software a seguir.*

|===
|Software ou Recurso |Versão Necessária 

|link:https://netbeans.org/downloads/index.html[+NetBeans IDE+] |Pacote de download do Java EE 

|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+JDK (Java Development Kit)+] |versão 7 ou 8 

|Servidor de aplicações em conformidade com Java EE |

link:http://www.oracle.com/technetwork/middleware/weblogic/overview/index.html[+Oracle WebLogic Server 11g-12c+], 
ou GlassFish Server Open Source Edition 3.x ou 4.x.
(Não funciona no Tomcat, a menos que o plug-in de suporte do EJB esteja instalado no Tomcat)

 
|O banco de dados jdbc/amostra no 
servidor de banco de dados JAVA DB (Derby) ou 
servidor de banco de dados MySQL

 |

No Java DB (Derby), o banco de dados jdbc/amostra é gerado pelo NetBeans IDE 
ao instalar o IDE com o servidor de aplicações GlassFish.

No MySQL, o IDE preenche o banco de dados de amostra após você tê-lo criado no servidor MySQL de dentro do IDE.

 
|===

O GlassFish Server pode ser instalado com a distribuição Web e Java EE do NetBeans IDE. Como alternativa, você pode visitar link:https://glassfish.java.net/download.html[+a página de downloads do GlassFish Server+].

*Importante: *os projetos Java EE 6 e Java EE 7 requerem GlassFish Server ou Oracle WebLogic Server 12c.


==  Introdução

Os Web services RESTful são serviços construídos com o estilo de arquitetura RESTful. A construção de Web services com a abordagem RESTful está surgindo como uma alternativa popular ao uso de tecnologias baseadas em SOAP para implantação de serviços na Internet, por ser mais leve e ter a capacidade de transmitir dados diretamente via HTTP.

O IDE oferece suporte ao rápido desenvolvimento de Web services RESTful usando a JSR 311 - API Java para Web services RESTful (JAX-RS) e Jersey, a implementação de referência para JAX-RS.

Para obter informações detalhadas, consulte:

* link:http://jcp.org/en/jsr/detail?id=311[+JSR 311: JAX-RS: A API Java dos Web Services RESTful+]
* link:http://jersey.dev.java.net/[+Jersey, a Implementação de Referência JAX-RS (JSR 311) de código-fonte aberto para construir Web services RESTful+]

Além de construir Web services RESTful, o IDE também oferece suporte ao teste e à construção de aplicações clientes que acessem Web services RESTful e à geração de código para chamar Web services (baseados em RESTful e em SOAP.)

Veja uma lista das funcionalidades RESTful fornecidas pelo IDE:

1. Criação rápida de Web services RESTful com base em padrões e classes de entidade JPA.
2. Geração rápida de código para chamar Web services como Google Maps, Yahoo News Search e o StrikeIron arrastando e soltando componentes do gerenciador de Web Services na janela Serviços.
3. Geração de Clientes Java RESTful para serviços registrados no gerenciador de Web Services.
4. Geração de cliente de teste para testar Web services RESTful.
5. View lógica para navegação fácil de classes de implementação do Web service RESTful no seu projeto.

Neste tutorial, você aprenderá como o IDE o ajuda na geração, implementação e teste de Web services RESTful.


== Web Services RESTful, Persistência e Classes de Entidade

Os Web services RESTful no Java dependem da link:http://en.wikipedia.org/wiki/Java_Persistence_API[+Java Persistence API+] para se comunicarem com um banco de dados. Especificamente, os Web services RESTful dependem de _classes de entidade_ e uma _unidade de persistência_, como definido na API de Persistência. As classes de entidade são classes Java que mapeiam para objetos em um banco de dados relacional. Conforme o link:http://download.oracle.com/javaee/5/tutorial/doc/bnbqa.html[+Tutorial Java EE5+], “Uma entidade é um objeto de domínio de persistência leve. Normalmente, uma entidade representa uma tabela em um banco de dados relacional, e cada instância da entidade corresponde a uma linha nessa tabela". Uma unidade de persistência consiste no conjunto de classes de entidades, na fonte de dados, no provedor da persistência e no próprio nome da unidade de persistência, como definido em um arquivo  ``persistence.xml`` .

Você pode usar o NetBeans IDE para criar classes de entidade e Web services RESTful no mesmo processo, ou você pode usar o IDE para criar Web services RESTful de classes de entidade existentes. Neste tutorial, use o assistente Serviços RESTful a partir do Banco de Dados para gerar classes de entidade e Web services RESTful no mesmo processo. O assistente gera automaticamente a unidade de persistência.


== Usando um Servidor de Banco de Dados MySQL

Se Você usar o servidor de bando de dados MySQL em vez de um JavaDB (Derby), você deverá registrar o servidor do banco de dados no IDE e adicionar o banco de dados de  ``amostra``  ao servidor.

*Para usar um servidor de banco de dados MySQL com este tutorial:*

1. Registre o servidor MySQL no IDE, se o servidor ainda não estiver registrado. Para registrar um servidor MySQL, vá à janela Serviços do IDE, clique com o botão direito do mouse no nó Banco de dados e selecione Registrar servidor MySQL. 
image::images/register-mysql-server.png[]
2. 
Uma caixa de diálogo será aberta, na qual você digitará os detalhes de configuração do seu servidor MySQL, incluindo o nome de usuário e senha de administrador. Consulte “Configurando as Propriedades do Servidor MySQL” em link:../ide/install-and-configure-mysql-server.html[+Conectando-se a um Banco de dados MySQL+].

image::images/basic-mysql-properties.png[]
3. Inicie o servidor MySQL e conecte-se a ele. Consulte “Iniciando o Servidor MySQL” em link:../ide/install-and-configure-mysql-server.html[+Conectando-se a um Banco de Dados MySQL+].
4. Clique com o botão direito do mouse no nó do servidor MySQL e selecione Criar Banco de Dados. A caixa de diálogo Criar Banco de Dados MySQL será aberta. 
image::images/create-database.png[]
5. Digite  ``sample``  como o novo nome do banco de dados. Conceda acesso total ao usuário raiz, ou ao usuário que você desejar.
image::images/new-database-name.png[]
6. Clique em OK. Uma caixa de diálogo é aberta, informando que  ``sample``  é o nome de um banco de dados de amostra e perguntando se você deseja criar tabelas, objetos e dados para esse banco de dados.
image::images/create-sample-contents.png[]
7. Clique em Sim. O IDE cria e preenche o banco de dados, e adiciona uma conexão ao banco de dados.
image::images/generated-db.png[]


== Criando Web Services RESTful de um Banco de dados

O objetivo deste exercício é criar um projeto e gerar classes de entidade e Web services RESTful com base em um banco de dados.

Esta seção usa o banco de dados JavaDB (Derby) e a fonte de dados jdbc/de amostra O JavaDB está incluído no SDK. A fonte de dados jdbc/amostra é gerada pelo NetBeans IDE automaticamente quando o IDE é instalado junto com o GlassFish.


=== Criando o Projeto

Para criar Web services RESTful, é necessário um projeto de aplicação Java Web.

*Para criar o projeto:*

1. Selecione Arquivo > Novo Projeto (Ctrl-Shift-N no Linux e no Windows, ⌘-Shift-N no MacOS). Em Categorias, selecione Java Web. Em Projetos, selecione Aplicação Web. Clique em Próximo. O assistente Nova Aplicação Web será aberto.

Como alternativa, você pode criar uma aplicação Web Maven. Selecione Arquivo > Novo Projeto (Ctrl-Shift-N no Linux e no Windows, ⌘-Shift-N no MacOS). Em Categorias, selecione Maven. Em Projetos, selecione Aplicação Web Maven e clique em Próximo.

2. Em Nome do Projeto, digite  ``CustomerDB`` . Clique em Próximo.
3. Selecione Java EE 6 Web ou Java EE 7 Web. Em Servidor, selecione o servidor que você deseja usar, mas observe que os projetos do Java EE exibe GlassFish server 3.x ou 4.x. Clique nas opções remanescentes e clique em Finalizar.

*Importante para Projetos Maven:* no NetBeans IDE 7.2 você não pode definir o servidor ao criar uma aplicação web Maven. Entretanto, você tem que definir o servidor antes de poder criar uma unidade de persistência. Portanto, após criar a aplicação web Maven, abra as Propriedades do projeto e defina o servidor nas propriedades de Execução. Para abrir as Propriedades do projeto, clique com o botão direito do mouse no nó Projeto e selecione Propriedades no menu de contexto.


=== Gerando Classes de Entidade e Serviços RESTful

Quando você tiver uma aplicação Java Web, adicione classes de entidade e Web services RESTful ao projeto.

*Para gerar classes de entidade e Web services RESTful: *

1. Clique com o botão direito do mouse no nó  ``CustomerDB``  e selecione Novo > Outro > Web Services > Web Services RESTful do Banco de dados. O assistente Novo Web Service RESTful é aberto, no painel Tabelas de Bancos de dados.
image::images/open-wizard.png[]
2. No painel Tabelas do Banco de dados, se estiver utilizando o GlassFish Server, selecione a fonte de dados  ``jdbc/sample``  no campo drop-down Fonte de Dados.

Se estiver utilizando o Tomcat, selecione jdbc:derby://localhost:1527/sample. Se o servidor de banco de dados Derby não iniciar automaticamente, será necessário iniciá-lo a partir da guia Bancos de dados na janela Serviços.

*Observação para usuários do MySQL:* É necessário criar uma nova fonte de dados. Selecione Nova Fonte de Dados, dê a ela um nome descritivo arbitrário e selecione a conexão de banco de dados  ``jdbc:mysql://localhost:3306/sample`` . Essa conexão foi estabelecida ao criar o banco de dados de amostra no MySQL. 
image::images/new-mysql-datasource.png[]

3. Em Tabelas Disponíveis, selecione CUSTOMER e, em seguida, clique em Adicionar. A tabela DISCOUNT_CODE, que tem um relacionamento com a tabela CUSTOMER, também é adicionada automaticamente à lista Tabelas Selecionadas. Se você estiver usando um banco de dados MySQL ou algumas versões do Derby, a tabela MICRO_MARKET também será adicionada. Você agora verá o seguinte (versão do Derby): 

image::images/select-tables.png[title="Painel Tabelas de Bancos de Dados do assistente Novas Classes de Entidade do Banco de Dados que mostra as tabelas CUSTOMER e DISCOUNT_CODE selecionadas"]
4. Clique em Próximo. A Página Classes de Entidade será aberta. Digite  ``entities``  como o nome do Pacote. Você agora verá o seguinte (versão do Derby).

*Observação:* O assistente Web Services RESTful do Banco de Dados gera automaticamente anotações JAXB. Se você gerar classes de entidade para uma aplicação Java EE com o assistente Classes de Entidade do Banco de dados e mais tarde quiser criar Web services RESTful com base nessas classes de entidade, certifique-se de que a caixa Gerar Anotações JAXB esteja marcada. Você também pode adicionar anotações JAXB manualmente às classes de entidade antes de executar o assistente Web Services RESTful de Classes de Entidade. Para obter mais informações, consulte link:http://netbeans.dzone.com/nb-generate-simpler-rest[+NetBeans para Gerar Web Services RESTful Mais Simples+].

image::../../../images_www/articles/71/websvc/rest/entity-classes.png[]
5. Clique em Próximo. Um painel será aberto no qual você poderá definir o nome e a localização das classes e pacotes de serviços gerados. Para projetos do Java EE, você tem a opção de alterar o nome e a localização da classe de configuração da aplicação REST.

Para este tutorial, aceite os defaults e clique em Finalizar. Quando você clica em Finalizar o IDE gera classes de entidade e serviço. Em um projeto Java EE, o IDE também gera uma classe de configuração de aplicação, que é uma subclasse de Application.

image::images/class-name-location.png[]

Agora, o IDE gera Web services RESTful. Quando o IDE tiver finalizado, observe a janela Projetos. As classes da entidade geradas estão no pacote  ``entities``  e os serviços estão no pacote  ``service`` . Os web services do Java EE RESTful EE6 de um banco de dados instanciam o  ``EntityManager``  em cada classe de serviço. Isso elimina a necessidade de classes do controlador JPA e gera códigos mais simples.


== Testando os Web Services RESTful

O objetivo deste exercício é testar sua aplicação. Você criará uma nova aplicação web para os testes e, em seguida, usará um assistente no IDE para gerar os testes no novo projeto.

1. Escolha Arquivo > Novo Projeto no menu principal.
2. Selecione o tipo de projeto Aplicação Web na categoria Java Web. Clique em Próximo.
3. Digite *WebServicesTest* para o nome do projeto. Clique em Próximo.
4. Selecione o GlassFish Server como servidor de destino e o Java EE 6 ou Java EE 7 como a versão do Java EE. Clique em Finalizar.
5. Clique com o botão direito do mouse no nó do projeto  ``CustomerDB``  e selecione Testar Web Services RESTful. Uma caixa de diálogo será aberta perguntando se você deseja gerar o cliente de teste dentro do projeto do serviço ou em um outro projeto Java Web. Essa opção permite a você driblar as restrições de segurança em alguns browsers. Você pode usar um projeto Web, contanto que ele esteja configurado para ser implantado no mesmo domínio de servidor que o projeto CustomerDB. 
image::../../../images_www/articles/71/websvc/rest/configure-test-client.png[]
6. Selecione *Cliente de Teste da Web no Projeto* e clique em Procurar.
7. Selecione o projeto WebServiceTest na caixa de diálogo Selecionar Projeto. Clique em OK.

O IDE gera o arquivo  ``test-resbeans.html``  no projeto WebServiceTest. O IDE também inicia automaticamente o servidor e implanta a aplicação CustomerDB.

Se a janela de saída mostrar uma mensagem de erro dizendo que uma ou mais classes não existe e que o projeto não pode ser construído, adicione as bibliotecas Jersey às bibliotecas de tempo de compilação. Clique com o botão direito do mouse no nó do projeto e selecione Propriedades. No menu em árvore Propriedades, selecione Bibliotecas. Clique em Adicionar Biblioteca e procure as bibliotecas Jersey.

8. Clique com o botão direito do mouse em WebServiceTest e escolha Executar.
9. Abra seu browser em link:http://localhost:8080/WebServicesTest/test-resbeans.html[+http://localhost:8080/WebServicesTest/test-resbeans.html+] 
image::../../../images_www/articles/71/websvc/rest/test-rest1.png[title="Página inicial de testes do Web service RESTful no browser"]

À esquerda está o conjunto de recursos raiz. Aqui eles são nomeados  ``entities.customer``  e  ``entities.discountCodes``  e  ``entities.microMarket`` .

10. Clique no nó  ``entities.customer`` . No campo "Escolher método para testar", selecione GET (application/json) ou GET (application/xml). Clique em Testar. O cliente de teste enviará uma solicitação e exibirá o resultado na seção Saída do Teste. O cliente de teste exibirá a View Bruta por default. A imagem a seguir mostra a resposta a uma solicitação aplicação/xml.
image::images/test-rest-raw.png[]

Existem 5 guias na seção Saída do Teste.

* A View Tabular é uma view nivelada que exibe todas as URI no documento resultante. Atualmente, essa view exibe apenas uma advertência de que relações conteúdo-continente não são permitidas.
* A View Bruta exibe os dados reais retornados. Dependendo do tipo de mime selecionado ( ``application/xml``  ou  ``application/json`` ), os dados exibidos estarão no formato XML ou JSON, respectivamente.
* A guia Sub-Recurso mostra os URLs do recurso raiz e dos sub-recursos. Quando o Web service RESTful tem como base classes de entidade de banco de dados, o recurso raiz representa a tabela do banco de dados e os sub-recursos representam as colunas.
* A guia Cabeçalhos exibe as informações do cabeçalho HTTP.
* A guia Monitor HTTP exibe as solicitações HTTP reais e as respostas enviadas e recebidas.

Saia do browser e retorne ao IDE.

link:/about/contact_form.html?to=3&subject=Feedback:%20Getting%20Started%20with%20REST%20Services%20in%20NetBeans%20IDE%20[+Enviar Feedback neste Tutorial+]


== Consulte Também

Para obter mais informações sobre o uso do NetBeans IDE para desenvolver aplicações Java EE, consulte os seguintes recursos:

* link:http://netbeans.dzone.com/nb-generate-simpler-rest[+NetBeans para Gerar Web Services RESTful Mais Simples+]
* link:../../trails/web.html[+Trilha do Aprendizado de Web services+]
* YouTube: link:http://www.youtube.com/watch?v=cDdfVMro99s[+RESTful Web Services, Building and Deploying (Part 1)+]
* YouTube: link:http://www.youtube.com/watch?v=_c-CCVy4_Eo[+NetBeans RESTful Testing and Invoking RESTful Resources (Part 2)+]

Para enviar comentários e sugestões, obter suporte e se manter informado sobre os mais recentes desenvolvimentos das funcionalidades de desenvolvimento Java EE do NetBeans IDE, link:../../../community/lists/top.html[+inscreva-se na lista de notícias nbj2ee@netbeans.org+].