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.
<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
Resultados
Você definiu operações válidas para os recursos.