Definindo Métodos de Recurso para os Aplicativos RESTful

Recursos individuais podem definir suas capacidades usando métodos HTTP suportados. Nos serviços Representational State Transfer (REST), os métodos suportados são GET, PUT, DELETE e POST. Todas as operações são normalmente conduzidas usando um dos métodos HTTP predefinidos com um recurso.

Antes de Iniciar

Entenda os métodos HTTP predefinidos e seus atributos conhecidos. Alguns métodos HTTP são considerados seguros, significando que a emissão do pedido não altera o recurso, ou considerados inalteráveis, significando que várias chamadas da operação não alteram o resultado. Enquanto que os métodos HTTP são definidos como tendo determinados atributos, a implementação do serviço segue as definições. Consulte as informações de definições de método de HTTP para saber mais sobre o conjunto comum de métodos para HTTP.

Sobre Esta Tarefa

Os clientes usam os métodos HTTP para executar determinadas operações. Diferentemente de outros sistemas distribuídos, em que interfaces exclusivas são definidas por cada sistema, sistemas RESTful baseados em HTTP dependem principalmente nos métodos predefinidos. Os quatro métodos mais comuns são GET, PUT, DELETE e POST. Os recursos não são necessários para permitir todos os métodos HTTP para todos os clientes.

O método HTTP GET recupera uma representação de recurso. Ele é protegido e inalterável. Os pedidos GET repetidos não alteram nenhum recurso.

O método HTTP PUT é normalmente usado para atualizar recursos ou para criar uma nova entidade em uma URL conhecida. Quando um recurso tiver que ser atualizado ou criado, um método HTTP PUT é emitido na URL de recurso com os novos dados de recurso que a entidade de pedido, também conhecido como corpo da mensagem. O método HTTP PUT é inalterável para que vários pedidos PUT idênticos com a mesma entidade na mesma URL gere o mesmo resultado como se apenas um pedido PUT fosse emitido. Esse método assume que nenhum outro pedido relevante foi feito.

O método de HTTP DELETE remove um recurso em uma URL específica.

O método de HTTP POST é frequentemente usado ao criar um recurso em uma coleção quando a URL do recurso final não é conhecida. Por exemplo, um administrador emite um pedido POST em um recurso de coleta /users que cria um usuário com um ID exclusivo, como 1234567890. O ID exclusivo é então usado como parte do caminho de URL para descrever o novo recurso de usuário, como /users/1234567790. Ele não é protegido e não é inalterável. Nesse caso, os vários pedidos POST para a coleta /users podem continuar criando um novo ID exclusivo e incluindo esse novo ID na coleta de usuários mesmo se o usuário tiver as mesmas informações.

Como a maioria dos serviços RESTful usa métodos HTTP bem conhecidos que fornecem resultados esperados, é possível criar clientes mais facilmente. Os desenvolvedores de serviço RESTful podem obter vantagem dos comportamentos esperados dos métodos HTTP. Os métodos de recursos também podem usar parâmetros, como parâmetros de caminho, de consulta ou de matriz para identificar o recurso. Consulte a definição do uso de parâmetros para as representações de pedido para recursos para saber mais.

(opcional) Se tiver um método de sub-recurso e um método de localizador de sub-recurso que têm uma anotação @Path com o mesmo valor na mesma classe de recurso, o localizador de sub-recurso não será considerado ao determinar o método a ser chamado por padrão. Isso está em conformidade com a especificação JAX-RS.

Use a propriedade wink.searchPolicyContinuedSearch com um valor true para modificar esse comportamento. Isso resulta no uso de localizadores de sub-recurso se nenhum método de sub-recurso corresponder à solicitação.

Para ativar a propriedade, inclua um arquivo de propriedades no diretório WEB-INF do módulo que possui a propriedade wink.searchPolicyContinuedSearch e um valor especificado. No arquivo web.xml do módulo do aplicativo, inclua um elemento init-param com o valor propertiesLocation para o elemento param-name. O elemento param-value especifica o local do arquivo de propriedades, por exemplo, WEB-INF/my_wink.properties.

O exemplo a seguir ilustra um arquivo web.xml:
<servlet>
    ...
    ...
    <init-param>
        <param-name>propertiesLocation</param-name>
        <param-value>/WEB-INF/my_wink.properties</param-value>
    </init-param>
</servlet>
O exemplo a seguir ilustra o arquivo de propriedades WEB-INF/my_wink.properties:
wink.searchPolicyContinuedSearch=true

No exemplo de código a seguir, a URL da solicitação termina com sayhello, mas a solicitação contém um POST em vez de um GET, portanto, uma mensagem de erro Método HTTP 405 Não Permitido é retornada. Certifique-se de que o método de HTTP enviado corresponda à anotação do método para evitar o 405.

@javax.ws.rs.Path("helloworld")
public class SampleResource {

...

@javax.ws.rs.Path("sayhello")
@javax.ws.rs.GET
public String getHello() { ...

Procedimento

  1. Identifique os tipos de recursos no aplicativo.
    Para cada classe de recurso, identifique um método existente ou crie um método que deseja chamar para cada método de HTTP suportado.Os métodos que respondem aos pedidos HTTP também são conhecidos como métodos de recursos.Para cada método de recurso na classe de recurso, anote o método Java™ com uma única anotação de método JAX-RS HTTP como @javax.ws.rs.GET, @javax.ws.rs.POST, @javax.ws.rs.DELETE ou @javax.ws.rs.PUT.Por exemplo, se um método de HTTP GET for suportado pela classe BooksCollection, poderá criar e anotar um método como o seguinte fragmento:
    @javax.ws.rs.Path("/bookstore/books/")
    public class BooksCollection {
        @javax.ws.rs.GET
        public String getBooksCollection() {
                    String str = /* Construct a String representation of the resource. */
            return str;
        }
    }
    Ao emitir uma solicitação HTTP GET para a URL http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books usando um navegador da web ou outro cliente HTTP, o método getBooksCollection() anterior é chamado.
  2. Certifique-se de que o recurso suporte os métodos HTTP necessários.
    Cada recurso normalmente possui vários métodos de recursos, como por exemplo:
    @javax.ws.rs.Path(“/bookstore/books/{bookID}”)
    public class Book {
            /* This is a database key. */
            private String ISBN;
    
            public Book(@javax.ws.rs.PathParam("bookID") String ISBN) {
                    this.ISBN = ISBN;
        }
    
        @javax.ws.rs.GET
        public String retrieveSpecificBookInformation() {
                    /* This code retrieves a book resource based on the ISBN key. */
        }
    
        @javax.ws.rs.PUT
        public String updateBookInformation(String updatedBookInfo) {
                    /* This code updates the book resource based on ISBN key and the entity (message body) sent
             in the request that is stored in updatedBookInfo. */
        }
    
        @javax.ws.rs.DELETE
        public void removeBook() {
                    /* This code deletes a book resource based on ISBN key. */
        }
    }
    Ao emitir uma solicitação HTTP GET para a URL http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books/<isbn_number> usando um navegador da web ou outro cliente HTTP, o método retrieveSpecificBookInformation() é chamado.Enviar o pedido HTTP PUT para a mesma URL chama o método updateBookInformation e qualquer conteúdo no corpo da mensagem de pedido é transmitido como o valor do objeto updatedBookInfo.Por fim, enviar um pedido HTTP DELETE para a mesma URL chama o método removeBook().
    Evitar Problemas Evitar Problemas: De acordo com a especificação JAX-RS, você não deve colocar várias anotações de método de HTTP, como @javax.ws.rs.POST ou @javax.ws.rs.PUT, no mesmo método de recurso. Como métodos de HTTP têm semântica definida exclusivamente, não use um método de recurso para vários métodos de HTTP.gotcha

Resultados

Você definiu operações válidas para os recursos.


Í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_httpmeth
Nome do arquivo: twbs_jaxrs_defresource_httpmeth.html