Definición de métodos de recursos para aplicaciones RESTful
Los recursos individuales pueden definir sus prestaciones utilizando métodos HTTP soportados. En los servicios Representational State Transfer (REST), los métodos soportados son GET, PUT, DELETE y POST. Todas las operaciones normalmente se llevan a cabo utilizando uno de los métodos HTTP predefinidos con un recurso.
Antes de empezar
Información para comprender los métodos HTTP predefinidos y sus atributos conocidos. Algunos métodos HTTP están pensados para que sean seguros, lo que significa que cuando se emite la solicitud no cambia el recurso, o idempotente, lo que significa que varias invocaciones de la operación no cambian el resultado. Aunque los métodos idempotente se definen para que tengan determinados atributos, la implementación del servicio sigue a las definiciones. Consulte las definiciones del método HTTP para obtener más información sobre el conjunto común de métodos para HTTP.
Acerca de esta tarea
Los clientes utilizan métodos HTTP para llevar a cabo determinadas operaciones. A diferencia de otros sistemas distribuidos donde se definen interfaces exclusivas de cada sistema, los sistemas RESTful basados en HTTP dependen principalmente de los métodos predefinidos. Los cuatro métodos más comunes son GET, PUT, DELETE y POST. No es necesario que los recursos permitan todos los métodos HTTP para todos los clientes.
El método GET de HTTP recupera una representación de recursos. Es seguro e idempotente. Las solicitudes GET repetidas no cambian ningún recurso.
El método PUT de HTTP se utiliza frecuentemente para actualizar los recursos o para crear una entidad nueva en un URL conocido. Cuando un recurso debe actualizarse o crearse, se emite un método PUT de HTTP en el URL del recurso con los mismos datos del recurso nuevo que la entidad de solicitud, también conocido como el cuerpo del mensaje. El método PUT de HTTP es idempotente por lo que múltiples solicitudes PUT idénticas con la misma entidad para el mismo URL producen el mismo resultado que si se hubiera emitido sólo una solicitud PUT. Este método da por supuesto que no se ha realizado ninguna otra solicitud relevante.
El método DELETE de HTTP elimina un recurso en un URL específico.
El método POST de HTTP se utiliza con frecuencia al crear un recurso en una colección cuando el recurso final URL no se conoce. Por ejemplo, un administrador emite una solicitud POST a un recurso de colecciones /users que crea un usuario con un ID exclusivo como, por ejemplo, 1234567890. El ID exclusivo se utiliza entonces como parte de la vía de acceso del URL para describir el recurso de usuario nuevo como, por ejemplo, /users/1234567790. No es seguro ni idempotente. En este caso, las diversas solicitudes POST a la colección /users pueden continuar con la creación de un nuevo ID exclusivo y agregar este nuevo ID a la colección de usuarios incluso si el usuario tiene la misma información.
Dado que la mayoría de los servicios RESTful utilizan métodos HTTP conocidos que generan resultados esperados, puede crear clientes de forma más fácil. Los desarrolladores del servicio RESTful pueden sacar partido de los comportamientos previstos de los métodos HTTP. Los métodos de recursos también pueden utilizar parámetros, tales como parámetros de vía de acceso, parámetros de consulta o parámetros de matriz para identificar los recursos. Si desea más información, consulte cómo definir la utilización de parámetros para representaciones de solicitudes en recursos.
(opcional) Si tiene un método de subrecurso y un método localizador de subrecursos que tienen una anotación @Path con el mismo valor en la misma clase de recurso, no se tiene en cuenta el localizador de subrecursos para determinar el método a invocar de forma predeterminada. Esto es en conformidad con la especificación JAX-RS.
Utilice la propiedad wink.searchPolicyContinuedSearch con el valor true para modificar este comportamiento. Como resultado, se obtienen localizadores de subrecursos que se utilizan si no hay métodos de subrecursos que coincidan con la solicitud.
Para habilitar la propiedad, incluya un archivo de propiedades en el directorio WEB-INF del módulo que tiene especificados la propiedad wink.searchPolicyContinuedSearch y el valor. En el archivo web.xml del módulo de aplicación, incluya un elemento init-param con el valor propertiesLocation para el elemento param-name. El elemento param-value especifica la ubicación del archivo de propiedades, por ejemplo, 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>
En el ejemplo siguiente se muestra un
archivo de propiedades WEB-INF/my_wink.properties:
wink.searchPolicyContinuedSearch=true
En el ejemplo de código siguiente el URL de la solicitud finaliza con sayhello pero la solicitud contiene un POST en lugar de un GET, por lo que se devuelve un mensaje de error HTTP 405 Método no permitido. Asegúrese de que el método HTTP enviado coincida con la anotación del método para evitar el error 405.
@javax.ws.rs.Path("helloworld")
public class SampleResource {
...
@javax.ws.rs.Path("sayhello")
@javax.ws.rs.GET
public String getHello() { ...
Procedimiento
Resultados
Ha definido operaciones válidas para los recursos.