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

  1. Identifique os tipos de recursos no aplicativo. Suponha que você possua dois tipos de recursos, BooksCollection e um objeto Book individual que possui as seguintes definições de classe:
    public class BooksCollection {
            public BooksCollection() {
                    /* no argument constructor */
        }
    
    }
    
    public class Book {
            public Book(String ISBN) {
                    /* This constructor has an argument that will be annotated with a JAX-RS annotation.
             See the JAX-RS specification for information on valid constructors. */
        }
    }
    Conforme definido na especificação JAX-RS, por padrão, as instâncias de recursos são criadas por pedido.Para o ambiente de tempo de execução JAX-RS para criar uma instância de recurso, é necessário ter um construtor com nenhum argumento ou um construtor com apenas parâmetros JAX-RS anotados presentes.
  2. Inclua a anotação @javax.ws.rs.Path em cada classe de recurso.  Para cada anotação @javax.ws.rs.Path, configure o valor como a parte da URL após a URL de base do aplicativo.
    /*
     * BooksCollection.java
      * This Java class represents the books collection URL at /bookstore/books.
     */
    @javax.ws.rs.Path("/bookstore/books/")
    public class BooksCollection {
    
    }
    Depois de concluir o aplicativo, poderá usar o recurso acessando http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books. Para essa URL, especifique o valor de raiz de contexto como a parte da URL após o módulo de contexto. Especifique o caminho de servlet como qualquer padrão de URL no arquivo web.xml, se existir.
  3. (opcional) Determine se um recurso precisa usar a parte da URL como parâmetro. Se um recurso precisar usar a parte da URL como um parâmetro, como um identificador, poderá usar a anotação @javax.ws.rs.Path com uma expressão regular.Em seguida, poderá incluir uma anotação @javax.ws.rs.PathParam no construtor de recurso ou no método de recurso.
    /*
      * Book.java represents individual books.
      */
    @javax.ws.rs.Path(“/bookstore/books/{bookID}”)
    public class Book {
           public Book(@javax.ws.rs.PathParam("bookID") String ISBN) {
    
       }
    }
    Quando um pedido HTTP é feito em http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books/ISBN_number, uma instância Book é criada com ISBN_number transmitida no parâmetro ISBN do construtor.

    Para obter informações adicionais sobre os outros parâmetros possíveis, consulte os parâmetros de definição para pedidos para recursos nos aplicativos RESTful.

  4. Crie a subclasse javax.ws.rs.core.Application para definir para o ambiente de tempo de execução JAX-RS quais classes fazem parte do aplicativo JAX-RS. As classes de recursos são retornadas no método getClasses(), como por exemplo:
    public class BookApplication extends javax.ws.rs.core.Application {
        public Set<Class<?>> getClasses() {
            Set<Class<?>> classes = new HashSet<Class<?>>();
            classes.add(BooksCollection.class);
            classes.add(Book.class);
            return classes;
        }
    }

    Ao definir a subclasse javax.ws.rs.core.Application, as classes retornadas a partir dos seus métodos são registradas no ambiente de tempo de execução JAX-RS. Ao configurar o arquivo web.xml, é necessário especificar a subclasse javax.ws.rs.core.Application como um parâmetro para o servlet ou filtro. Para obter informações adicionais, consulte a configuração do arquivo web.xml para os aplicativos JAX-RS.

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.


Ícone que indica o tipo de tópico Tópico de Tarefa



Ícone de registro de data e hora Última atualização: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_uri
Nome do arquivo: twbs_jaxrs_defresource_uri.html