![Fechar [x]](http://dw1.s81c.com/i/c.gif){kind=small}
REST (Representational State Transfer) é um estilo de arquitetura que permite o desenvolvimento de sistemas fracamente acoplados usando o protocolo HTTP. Tradicionalmente, o design dos serviços com base em REST (ou serviços da web RESTful) foi descrito em termos de URIs, recursos, métodos HTTP suportados por cada recurso e suas representações. Essas descrições são normalmente publicadas como documentação a fim de permitir a implementação do serviço e também que os clientes do serviço reconheçam e usem o serviço da web. Devido a falta de alguma notação formal, essas descrições existem invariavelmente em documentos de design como texto e tabelas, o que nos leva a alguns desafios nesta abordagem:
- Como projetar seu serviço da web RESTful?
- Como implementar esse design?
- Como publicar seus serviços RESTful para disponibilizá-los aos usuários?
- Como desenvolver esse design e implementação?
O IBM® Rational® Software Architect versão 8.0.3 aborda esses desafios dentro do paradigma de model-driven development (MDD), com o suporte para modelagem e implementação de serviços da web RESTful. O suporte de modelagem permite que você crie modelos UML para seu serviço da web a fim de descrever seu serviço da web. O mesmo modelo UML também serve como a fonte para a geração da documentação para aqueles que usam seu serviço da web. No lado da implementação, você gera um código Java a fim de gerar seu serviço da web, usando a API Java para Serviços da web RESTful ou JAX-RS.
Com isso em mente, vamos explorar os recursos da modelagem REST do Rational Software Architect. Ao final deste artigo, você estará apto a projetar e a implementar um serviço de marcador RESTful com base no modelo UML exibido na Figura 1.
Figura 1. Modelo de serviço da web de marcador RESTful
O design do serviço da web RESTful começa com um modelo UML. O Rational Software Architect inclui dois modelos nos quais basear seu design (exibidos na Figura 2).
Figura 2. Modelos REST
Escolha o modelo JAX-RS Service Model se sua implementação final do serviço RESTful tiver base no JAX-RS. Ou, se você ainda não estiver preocupado com a implementação ou não quiser usar JAX-RS, selecione o modelo REST Service Model . Esses modelos vêm predefinidos com as diversas paletas e bibliotecas necessárias para modelar o serviço.
Após a criação do modelo, você normalmente verá o diagrama principal do modelo. Nesse diagrama, é possível ver a paleta REST no lado esquerdo, usada para criar elementos REST e uma paleta dos elementos do modelo para sua escolha no lado direito.
Figura 3. Diagrama principal e paleta REST
Use essa paleta para criar diversos elementos que formam um serviço da web RESTful.
Comece criando um aplicativo.
- Clique na entrada da paleta Application Class e clique em um espaço vazio no diagrama.
- Nomeie essa classe
BookmarkApplication. Essa classe de aplicativo representa a raiz do serviço da web RESTful. - Em seguida, adicione os recursos RESTful que esse aplicativo deve expor.
Cada recurso é exposto em um URI e pode oferecer suporte a qualquer um dos métodos HTTP. Por exemplo, para o serviço da web de marcador, é possível expor seus recursos como mostra a Tabela 1.
Tabela 1. Recursos e URIs
| Recursos | URI | Métodos HTTP suportados | |
|---|---|---|---|
| Usuários | /users | GET | getListofUsers |
| POST | createUser | ||
| Usuário | /users/{username} | GET | getUser |
| DELETE | deleteUser | ||
| Marcadores | /users/{username}/bookmarks | GET | getListofBookmarks |
| POST | createBookmark | ||
| Marcador | /users/{username}/bookmarks/{bookmarkId} | GET | getBookmark |
| DELETE | deleteBookmark | ||
A partir dessa tabela, você tem o recurso Users acessível por meio do URI /users na raiz de seu aplicativo.
- Para criar os recursos, clique em Resource Class na paleta e clique em um espaço vazio no diagrama e nomeie essa classe, Users.
- URIs REST são modeladas como caminhos. Portanto, para modelar o URI /user, clique na entrada Path Dependency na paleta e clique e arraste da classe BookmarkApplication no diagrama para a classe Users e nomeie esse caminho
/users.
Em seguida, você pode adicionar os métodos REST suportados por esse recurso.
Para o recurso Users, o software oferece suporte aos métodos HTTP GET e POST, de modo que você possa clicar na operação GET , clicar na classe Users no diagrama e nomear a operação getListofUsers.
Da mesma maneira, repita essas ações para a operação POST e nomeie-a createUser.
Observação:
a partir da perspectiva REST, esses são os métodos HTTP GET e POST, mas aqui você deu a eles nomes mais descritivos.
Seu diagrama deve parecer um pouco com a Figura 4.
Figura 4. Diagrama BookmarkApplication e Users
- Agora, você pode adicionar o restante dos recursos, caminhos e operações.
Seu diagrama final parecerá um pouco com a Figura 5.
Figura 5. Modelo UML
Visualização maior da figura 5.
Para a operação GET getUser no recurso Usuário, perceba que o URI é /users/{username}. Aqui, {username} é um parâmetro para esse recurso. Para especificar seu uso na operação getUser , clique no parâmetro Param na paleta e clique na operação getUser no diagrama principal. Isso criará um parâmetro para essa operação.
Observação:
após a criação do parâmetro, talvez ele não esteja visível no diagrama. Isso ocorre porque, por padrão, os parâmetros são filtrados em diagramas. Para torná-lo visível, clique com o botão direito do mouse na classe User no diagrama e selecione Filter > Show Signature.
É possível especificar detalhes desse parâmetro na guia REST na visualização Properties (Figura 6). Para esse parâmetro, selecione PathParam, pois ele é extraído do caminho e selecione username como nome. Também é possível especificar se o parâmetro é Header ou Query e assim por diante, com base em seu design. Além disso, é possível especificar um valor padrão.
Figura 6. Guia REST Parameter
Para manter a consistência, recomendamos que o nome UML para esse parâmetro seja igual ao nome REST (ou parecido).
- Para fazer isso, alterne para a guia General e mude o nome para
username. - Além disso, na guia General, especifique o tipo UML do parâmetro como String.
A diferença no tipo REST (PathParam) e no tipo UML (String) é que o tipo REST é o tipo na interface REST para o usuário do serviço REST, enquanto o tipo UML é o tipo de parâmetro usado pela implementação do serviço REST.
Para cada método REST, também é necessário especificar o formato dos dados suportados para entrada e saída.
- Selecione o método getUser e alterne para a guia REST na visualização Properties.
- Clique dentro da lista Produces (ou Consumes) para especificar o formato.
Há um conjunto de valores predefinidos entre os quais você pode escolher (veja a Figura 7) ou insira um tipo de sua preferência. Para Produces e Consumes, é possível especificar diversos tipos.
- Selecione application/xml para a seção Produces.
Figura 7. Propriedades produzidas e usadas pelo método REST
Mais abaixo nessa guia, é possível especificar os códigos de retorno HTTP que esse método pode retornar.
- Clique dentro da lista Return codes para selecionar um código de retorno.
- Selecione 200 OK como um código de retorno e 404 Not Found como outro.
Os códigos de retorno HTTP padrão estão disponíveis no menu suspenso ou também é possível digitar seu código personalizado. Para cada código de retorno, é possível especificar um exemplo do conteúdo que pode ser retornado e adicionar uma descrição nas caixas de texto Content e Description, respectivamente.
Figura 8. Propriedades do código de retorno do método REST
Modelando interações RESTful em diagramas de sequência
É possível modelar as interações típicas com os clientes de seu serviço da web RESTful usando os diagramas de sequência. As chamadas entre o cliente e seu serviço são essencialmente chamadas HTTP; portanto, um elemento de interação HTTP é fornecido dentro da biblioteca HTTPReference (veja a Figura 9).
Figura 9. Elementos de interação HTTP
O HTTPReference já terá sido importado em seus modelos se você tiver usado o REST ou o modelo JAX-RS para criar o modelo.
O elemento de interação HTTP é usado para representar o cliente e o serviço da web RESTful.
- Para usar isso em um diagrama de sequência, clique e arraste o elemento de interação HTTP do Project Explorer para um diagrama de sequência e dê a ele um nome apropriado, por exemplo
Clientpara cliente,Bookmark Servicepara o serviço da web. - Agora, você pode trocar mensagens entre o cliente e o serviço da web.
- À medida que você troca cada mensagem, é possível selecionar um tipo de operação na lista de Solicitações e Respostas HTTP para essa mensagem no menu suspenso (Figura 10). Normalmente, para mensagens do cliente para o serviço da web, escolha uma solicitação GET, POST, DELETE, por exemplo.
Figura 10. Solicitação HTTP em um diagrama de sequência
- E para o retorno, selecione um código de retorno, como 200 OK.
Figura 11. Resposta HTTP em um diagrama de sequência
- Também é possível detalhar cada solicitação ou resposta com relação ao URI, cabeçalhos e conteúdo usando a guia HTTP Properties para uma mensagem (Figura 12).
Figura 12. Detalhes do método HTTP
O suporte ao diagrama de sequência é bastante útil para os clientes de seu serviço da web entenderem o fluxo de trabalho suportado.
- Para o lado da implementação, é possível detalhar ainda mais o diagrama de sequência com chamadas para classes de recurso reais arrastando suas classes de recurso nos diagramas de sequência e traçando mensagens para o diagrama.
Figura 13. Diagrama de sequência para implementação
Gerando a documentação usando relatórios BIRT
Relatórios Business Intelligence and Reporting Tools (BIRT) são uma maneira fácil de compartilhar ou publicar a documentação de seu serviço da web RESTful. O Rational Software Architect inclui um modelo de relatório REST para ser usado com seus modelos REST. Também é possível editar e aprimorar o relatório de acordo com suas necessidades de documentação.
- Para criar um relatório REST, selecione File > New > Other > REST Modeling Reports > REST Report.
Figura 14. Relatório REST
Implementando o serviço da web usando JAX-RS
Quando o modelo estiver pronto, use a transformação UML-to-Java com a extensão JAX-RS para gerar a implementação do serviço. No entanto, antes de fazer isso, é necessário adicionar alguns detalhes específicos de JAX-RS ao seu modelo.
O primeiro detalhe são as operações do localizador de sub-recursos. No modelo REST, você traçou a dependência Path a fim de fornecer navegação de um recurso para outro.
- Na implementação JAX-RS, você precisa criar uma operação de localizador de sub-recurso no recurso de origem. É possível criar um método SubResourceLocator a partir da paleta.
Figura 15. Paleta JAX-RS
- Para que a operação do localizador seja completamente definida, é preciso definir seu tipo de retorno como o recurso de destino e definir também sua propriedade de estereótipo do localizador (SubResourceLocator) como o valor do caminho (<Path/bookmarks> neste exemplo), como mostra a Figura 16.
Figura 16. Propriedades do localizador de sub-recursos
- Além disso, você precisa adicionar tipos específicos de JAX-RS às suas operações.
Por exemplo, convém usar o objeto javax.ws.rs.core.Response como um tipo de retorno. Esses tipos estão disponíveis na biblioteca de referência JAX-RS (veja a Figura 17).
Figura 17. Biblioteca de referência JAX-RS
- Agora, é possível criar uma configuração da transformação UML-to-Java a fim de gerar o código para o serviço. A fonte da configuração deve ser o modelo criado por você e o destino deve ser um projeto da web dinâmico, habilitado com bibliotecas JAX-RS.
- Também será necessário ativar a extensão JAX-RS UML-to-Java5 (Figura 18) na guia de extensões da configuração da transformação.
Figura 18. Extensão da transformação JAX-RS UML-to-Java5
Essa extensão cuida da geração de anotações JAX-RS nas classes Java e das atualizações necessárias ao arquivo web.xml para o serviço.
- A execução dessa transformação gerará as classes de Java necessárias à sua implementação e, então, você poderá adicionar a lógica de implementação exigida às suas classes.
Agora, é possível agrupar e implementar esse aplicativo em um IBM® WebSphere® Application Server com Feature Pack para Web 2.0 e Mobile, que oferece suporte a JAX-RS.
- Se você tiver o WebSphere Application Server Test Environment instalado com o Rational Software Architect, poderá clicar com o botão direito do mouse em seu projeto da web dinâmico e selecionar Debug As > Debug on Server e selecionar o servidor de teste.
Depois disso, você poderá testar e depurar seu serviço da web RESTful dentro do ambiente do Rational Software Architect.
Observação:
é possível usar qualquer implementação JAX-RS para aplicar suas implementações (por exemplo Apache Wink). Não é necessário usar o WebSphere Application Server.
A transformação UML-to-Java com a extensão JAX-RS fornece um suporte completo para engenharia roundtrip. Dessa forma, você pode modelar e gerar um código e, posteriormente, refinar o modelo e atualizar o código ou até mesmo atualizar o código e usar a transformação UML-to-Java no modo Reconcile para atualizar o modelo a partir do código.
Se você já tiver um projeto da web dinâmico com base no JAX-RS, use a transformação Java-to-UML com a extensão JAX-RS para gerar um modelo UML a partir de seu projeto. Isso pode servir como um bom ponto de partida para você entender suas implementações JAX-RS e refiná-las ainda mais.
Este artigo cobriu apenas brevemente o suporte para JAX-RS. Um artigo futuro explorará as especificidades do JAX-RS em detalhes.
Você aprendeu como modelar e implementar serviços da web RESTful usando o suporte para desenvolvimento conduzido por modelo no Rational Software Architect. Uma abordagem baseada no modelo facilita o design, implementação e evolução de seus serviços da web RESTful.
É possível fazer o download o modelo de serviço de marcador a fim de explorar mais (consulte a seção Downloads ). Além disso, você encontrará informações mais úteis na seção Recursos deste artigo.
| Descrição | Nome | Tamanho | Método de download |
|---|---|---|---|
| Bookmark service UML model | Bookmarks_Service_Model.zip | 6KB | HTTP |
Informações sobre métodos de download
Aprender
- Lembre-se de consultar esses recursos relacionados a este artigo:
- Para saber mais sobre o Rational Software Architect, comece pela página do developerWorks . Explore também a visão geral do produto, o centro de informações para instruções de instalação e uso e o wiki do Rational Software Architect para obter mais recursos.
- Confira os slides e vídeo sobre modelagem REST neste tópico do wiki do Rational Software Architect: RSA v8 What's New, Generating of REST-style services.
- Obtenha o WebSphere Application Server Feature Pack for Web 2.0 and Mobile
- Consulte JSR 311: JAX-RS: The JavaTM API for RESTful Web Services, entre Java Specification Requests no website do Java Community Process.
- Talvez você também considere este blog útil: An example of modeling REST web services
- Visite a área do software Rational no developerWorks para visualizar os recursos técnicos e as melhores práticas dos produtos da Rational Software Delivery Platform.
- Fique por dentro dos eventos técnicos e webcasts do developerWorks com foco em uma variedade de produtos da IBM e tópicos do segmento de mercado de TI.
- Participe de um briefing ao vivo e gratuito do developerWorks para se atualizar rapidamente sobre produtos e ferramentas IBM, bem como tendências do segmento de mercado de TI.
- Acompanhe as Demos on demand do developerWorks, variando de demos de instalação e configuração de produtos para iniciantes a funcionalidades avançadas para desenvolvedores experientes.
- Melhore suas qualificações. Consulte o Catálogo de treinamento e certificação do Rational que inclui muitos tipos de cursos em uma ampla variedade de tópicos. É possível fazer alguns deles em qualquer momento e lugar, e muitos dos cursos “Getting Started” são grátis.
Obter produtos e tecnologias
- Faça o download de uma ou de ambas as versões de teste:
- Avalie o software IBM da forma que melhor lhe convier: faça o download para uma versão de testes, experimente on-line, use em um ambiente de nuvem ou passe algumas horas no SOA Sandbox aprendendo a implementar Arquitetura Orientada a Serviços de forma eficiente.
Discutir
- Participe da discussão no fórum Rational Development Tools.
- Classifique ou revise o software Rational. É rápido e fácil. Realmente.
- Compartilhe seu conhecimento e ajude outros a usar o software Rational, escrevendo um artigo para o developerWorks. Descubra quais são as características de um bom artigo do developerWorks e como realizá-lo.
- Siga o software Rational no Facebook, Twitter (@ibmrational) e no YouTube e adicione seus comentários e solicitações.
- Faça e responda a perguntas, e aumente seu conhecimento participando dos Fóruns do Rational, cafése de wikis.
- Obtenha liderança em pensamento social. Faça parte da comunidade Rational para compartilhar seu conhecimento em software Rational e ficar conectado a seus colegas.
Índice
Conheça a IBM da sua cidade
Tags
Use a barra de rolagem para ver mais ou menos tags.
Tags populares mostra as principais tags para esta zona de conteúdo em particular (por exemplo, Java technology, Linux, WebSphere).
Minhas tags mostra suas tags para esta zona de conteúdo em particular (por exemplo, Java technology, Linux, WebSphere).
Tags de artigo populares |
Minhas tags de artigoIr para lista de tags
Tags de artigo populares |
Minhas tags de artigo