Definindo Padrões de URI para Recursos nos Aplicativos RESTful
Os serviços Representational State Transfer (REST) baseiam-se na manipulação de recursos. Os recursos para os serviços RESTful são endereçáveis e as URLs são a principal maneira de obter a endereçabilidade no REST.
Antes de Iniciar
Identifique os recursos no aplicativo que deseja expor como um serviço RESTful.
Sobre Esta Tarefa
As URLs são usadas para especificar o local de um recurso. A interação entre o servidor e o cliente baseia-se na emissão de operações HTTP para URLs. A definição de padrões de URL é importante porque as URLs normalmente possuem um tempo de vida longo, assim, os clientes podem endereçar diretamente um recurso longo depois que o recurso for inicialmente descoberto.
URLs são tipicamente usadas quando você insere endereços em navegadores da Web, como http://www.ibm.com/ ou http://www.example.com/bookstore/books/ISBN123. Embora as URLs não precisam ser entendidas pelos usuários, os serviços RESTful que fornecem URLs lógicas nos padrões legíveis permitem que os desenvolvedores de aplicativo cliente trabalhem eficientemente.
Os clientes RESTful usam URLs para manipular recursos. Cada recurso deve possuir uma URL exclusiva. Alguns padrões de URL possuem um caminho de coleta com um identificador exclusivo anexado. Por exemplo, é possível usar http://www.example.com/bookstore/books como a URL de recurso de coleta, http://www.example.com/bookstore/books/ISBN123 como a URL de recurso de manual exclusivo e usar http://www.example.com/bookstore/books/ISBN123/authors para recuperar um recurso de coleta que descreve os autores ISBN123.
O desenvolvedor de aplicativo deve cuidadosamente considerar a granularidade das URLs porque pode afetar o uso do aplicativo e o desempenho. Por exemplo, é possível incluir as informações do autor de um manual como parte do recurso de manual ou pode definir as informações de autor como um recurso exclusivo com sua própria URL que é referenciada no recurso de manual. Dependendo da reutilização de recursos, pode ser mais eficiente definir um recurso separado para as informações de autor que são referenciadas em um hyperlink do recurso de manual para casos em que o autor escreve um manual diferente.
Depois que uma URL inicial for fornecida para um cliente, pedidos subsequentes relacionados são descobertos ao analisar o recurso atual. No exemplo de manual, um pedido GET para http://www.example.com/bookstore/books/ recupera uma lista de URLs de manuais que podem incluir http://www.example.com/bookstore/books/ISBN123.
Como os sistemas dependem dos recursos que estão sendo disponíveis, as URLs normalmente possuem longevidade. Como o HTTP tinha códigos de status integrados para redirecionamento, como o código 301 movido permanentemente e o código 307 redirecionado temporariamente, os usuários e clientes com caches normalmente reutilizam primeiro as URLs descobertas anteriormente. Além disso, é possível considerar a inclusão de um identificador de versão no padrão de URL, como http://www.example.com/bookstore/v2/books/ISBN123. Tal como o planejamento envolvido para definir uma interface usando um código Java™, certifique-se de escolher cuidadosamente os padrões de URL por causa da longevidade esperada.
Na API Java para os Serviços da Web RESTful (JAX-RS), é necessário incluir anotações @Path nos arquivos de classe Java ou os métodos Java para definir a URL relativa do recurso. É possível usar os localizadores de sub-recurso JAX-RS e os métodos de sub-recurso para definir recursos. Use parâmetros, como parâmetro de caminho ou de matriz na URL para identificar o recurso.
O valor na anotação @Path define a parte relativa da URL completa para seu recurso. A URL base é derivada a partir do domínio, porta, raiz de contexto de módulo de aplicativo e qualquer mapeamento de padrão de URL no arquivo web.xml do módulo de aplicativo. Por exemplo, se o domínio for www.example.com, a porta será 9060, a raiz de contexto de módulo será example, o padrão de URL de servlet será store/* e o valor da anotação @Path será /bookstore/books. A URL integral é: http://www.example.com:9060/example/store/bookstore/books.
Procedimento
Resultados
Você criou uma URL para identificar seus recursos para o serviço RESTful. Ao considerar os problemas com os padrões de URL logo no início do design do aplicativo, o serviço RESTful aumenta a usabilidade e o valor por um tempo prolongado.
O que Fazer Depois
O recurso na URL definida existe. Entretanto, o recurso ainda não possui nenhum método para manipular as ações de método de HTTP, como GET, POST, PUT ou DELETE. Consulte a definição dos métodos de recurso para aplicativos RESTful para saber mais sobre a definição de capacidades de recursos usando métodos HTTP suportados.