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.

En el ejemplo siguiente se muestra un archivo web.xml:
<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

  1. Identifique los pasos de los recursos en la aplicación.
    Para cada clase de recurso, identifique un método existente o cree un método que desee invocar para cada método HTTP soportado. Los métodos que responden a solicitudes HTTP también se conocen como métodos de recursos. Para cada método de recurso de la clase de recursos, anote el método Java™ con una sola anotación de método HTTP de JAX-RS como @javax.ws.rs.GET, @javax.ws.rs.POST, @javax.ws.rs.DELETE o @javax.ws.rs.PUT. Por ejemplo, si un método GET de HTTP recibe soporte por parte de la clase BooksCollection, puede crear y anotar un método como el fragmento siguiente:
    @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;
        }
    }
    Al emitir una solicitud GET de HTTP en el URL http://<nombre_host>:<puerto>/<raíz_contexto>/<vía_acceso_servlet>/bookstore/books utilizando un navegador web u otro cliente HTTP, se invocará al método getBooksCollection() anterior.
  2. Asegúrese de que el recurso dé soporte a los métodos HTTP necesarios.
    Normalmente, cada recurso tiene varios métodos de recursos; por ejemplo:
    @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. */
        }
    }
    Cuando se emite una solicitud GET de HTTP en el URL http://<nombre_host>:<puerto>/<raíz_contexto>/<vía_acceso_servlet>/bookstore/books<número_isbn> utilizando un navegador web u otro cliente HTTP, se invocará al método retrieveSpecificBookInformation() anterior. El envío de una solicitud PUT de HTTP en el mismo URL invoca al método updateBookInformation y cualquier contenido en el cuerpo del mensaje de solicitud se pasa como el valor del objeto updatedBookInfo. Finalmente, el envío de una solicitud DELETE de HTTP al mismo URL invoca al método removeBook().
    Avoid trouble Avoid trouble: De acuerdo con la especificación de JAX-RS, no se debe colocar varias anotaciones de método HTTP, tales como @javax.ws.rs.POST o @javax.ws.rs.PUT en el mismo método de recurso. Puesto que los métodos HTTP tienen semántica definida en exclusiva, no utilice un método de recursos para varios métodos HTTP.gotcha

Resultados

Ha definido operaciones válidas para los recursos.


Icon that indicates the type of topic Task topic



Timestamp icon Last updated: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_httpmeth
File name: twbs_jaxrs_defresource_httpmeth.html