Definición de los patrones de URI para recursos en aplicaciones RESTful

Los servicios REST (Representational State Transfer) se basan en recursos de manipulación. Los recursos para los servicios RESTful son direccionables, y los URL son el principal modo de conseguir la direccionabilidad en REST.

Antes de empezar

Identifique los recursos en la aplicación que desee exponer como servicio RESTful.

Acerca de esta tarea

Los URL se utilizan para especificar la ubicación de un recurso. La interacción entre el servidor y el cliente se basa en la emisión de operaciones HTTP para los URL. La definición de patrones de URL es importante porque los URL a menudo tienen una larga duración de modo que los clientes pueden dirigir directamente un recurso mucho después de haber descubierto inicialmente el recurso.

Los URL normalmente se utilizan cuando se entran direcciones en navegadores web, como, por ejemplo, http://www.ibm.com/ o http://www.example.com/bookstore/books/ISBN123. Aunque no es necesario que los URL sean comprensibles para los usuarios, los servicios RESTful que proporcionan URL lógicos en patrones comprensibles permiten a los desarrolladores de aplicaciones cliente efectuar un trabajo eficaz.

Los clientes RESTful utilizan URL para manipular recursos. Cada recurso debe tener su propio URL exclusivo. Algunos de los patrones de URL tienen una vía de acceso de colección con un identificador exclusivo añadido. Por ejemplo, puede utilizar http://www.example.com/bookstore/books como URL de recursos de colección, http://www.example.com/bookstore/books/ISBN123 como un URL de recursos de libro exclusivo y puede utilizar http://www.example.com/bookstore/books/ISBN123/authors para recuperar un recurso de colección que describe los autores de ISBN123.

El desarrollador de aplicaciones debe considerar cuidadosamente la granularidad de los URL porque puede afectar a la utilización de la aplicación y al rendimiento. Por ejemplo, puede incluir la información del autor de un libro como parte del recurso de publicación o puede definir la información del autor como un recurso exclusivo con su propio URL al que se hace referencia en el recurso del libro. Dependiendo de la reutilización de los recursos, es posible que resulte más eficaz definir un recurso independiente para la información del autor al que se hace referencia en un hiperenlace del recurso de la publicación para los casos en los que el autor escriba un libro diferente.

Después de asignar un URL inicial a un cliente, las solicitudes relacionadas posteriores se descubren analizando el recurso actual. En el ejemplo del libro, una solicitud GET para http://www.example.com/bookstore/books/ recupera una lista de URL de publicaciones que pueden incluir http://www.example.com/bookstore/books/ISBN123.

Dado que los sistemas se basan en los recursos que están disponibles, los URL generalmente son longevos. Puesto que HTTP tiene incorporados códigos de estado para la redirección como, por ejemplo, el código 301 movido de forma permanente y el código 307 redirigido de forma temporal, los usuarios y clientes con memorias caché a menudo reutilizan primero los URL descubiertos anteriormente. Además puede incluir un identificador de versión en el patrón de URL, como, por ejemplohttp://www.example.com/bookstore/v2/books/ISBN123. Al igual que la planificación implicaba tener que definir una interfaz utilizando el código Java™, asegúrese de elegir cuidadosamente los patrones de URL debido a la longevidad prevista.

En Java API for RESTful Web Services (JAX-RS), debe añadir anotaciones @Path a los archivos de clase Java o los métodos Java para definir el URL relativo del recurso. Puede utilizar los ubicadores de subrecursos de JAX-RS y los métodos de subrecursos para definir recursos. Utilice parámetros, como el parámetro path o el parámetro matrix, en el URL para identificar el recurso.

El valor de la anotación @Path define la relación parte relacionada con el URL completo para el recurso. El URL base deriva del dominio, el puerto, la raíz de contexto del módulo de la aplicación y cualquier correlación de patrones de URL en el archivo web.xml del módulo de la aplicación. Por ejemplo, si el dominio se www.example.com, el puerto es 9060, el raíz de contexto del módulo es example, el patrón de URL del servlet es store/* y el valor de la anotación @Path es /bookstore/books. El URL completo es: http://www.example.com:9060/example/store/bookstore/books.

Procedimiento

  1. Identifique los pasos de los recursos en la aplicación. Supongamos que tiene dos tipos de recursos, un BooksCollection y un objeto Book individual que tienen las siguientes definiciones de clase:
    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. */
        }
    }
    Tal como se define en la especificación de JAX-RS, de forma predeterminada, se crean instancias de recursos por solicitud. Para que el entorno de ejecución de JAX-RS cree una instancia de recurso, debe tener o un constructor sin ningún argumento o un constructor con sólo parámetros anotados JAX-RS que estén presentes.
  2. Añada una anotación @javax.ws.rs.Path a cada clase de recurso.  Para cada anotación @javax.ws.rs.Path, establezca el valor como parte del URL después del URL base de la aplicación.
    /*
     * BooksCollection.java
      * This Java class represents the books collection URL at /bookstore/books.
     */
    @javax.ws.rs.Path("/bookstore/books/")
    public class BooksCollection {
    
    }
    Tras completar la aplicación, puede utilizar el recurso visitando http://<nombre_host>:<puerto>/<raíz_contexto>/<vía_acceso_servlet>/bookstore/books. Para este URL, especifique el valor de la raíz de contexto como parte del URL después del módulo de contexto. Especifique la vía de acceso del servlet como cualquiera de los patrones URL en el archivo web.xml, si existe.
  3. (opcional) Determine si un recurso necesita utilizar parte del URL como parámetro. Si un recurso necesita utilizar parte del URL como parámetro, como por ejemplo un identificador, puede utilizar la anotación @javax.ws.rs.Path con una expresión regular. A continuación, puede añadir una anotación @javax.ws.rs.PathParam en el constructor de recursos o en el método de recursos.
    /*
      * Book.java represents individual books.
      */
    @javax.ws.rs.Path(“/bookstore/books/{bookID}”)
    public class Book {
          public Book(@javax.ws.rs.PathParam("bookID") String ISBN) {
    
       }
    }
    Cuando se realiza una solicitud HTTP a http://<nombre_host>:<puerto>/<raíz_contexto>/<vía_acceso_servlet>/bookstore/books/número_ISBN, se creará una instancia Book con número_ISBN que pasa al parámetro ISBN del constructor.

    Para obtener más información acerca de los demás parámetros posibles, consulte la información sobre la definición parámetros para las solicitudes a recursos de aplicaciones RESTful.

  4. Cree la subclase javax.ws.rs.core.Application para definirla en el entorno de ejecución de JAX-RS en el que las clases forman parte de la aplicación de JAX-RS. Las clases de recursos se devuelven en el método getClasses(); por ejemplo:
    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;
        }
    }

    Al definir la subclase javax.ws.rs.core.Application, las clases devueltas de sus métodos se habrán registrado en el entorno de ejecución de JAX-RS. Cuando se configura el archivo web.xml, debe especificar la subclase javax.ws.rs.core.Application como parámetro para el servlet o el filtro. Para obtener más información, consulte la información sobre la configuración del archivo web.xml para aplicaciones de JAX-RS.

Resultados

Ha creado un URL para identificar los recursos del servicio RESTful. Gracias a la consideración de problemas con los patrones de URL al principio del diseño de la aplicación, el servicio RESTful aumenta la usabilidad y su valor durante un tiempo prolongado.

Qué hacer a continuación

Existe el recurso en el URL definido. Sin embargo, el recurso todavía no tiene ningún método para gestionar acciones HTTP tales como GET, POST, PUT o DELETE. Consulte la definición de métodos de recurso para aplicaciones RESTful si desea obtener más información acerca de la definición de funciones de recursos utilizando métodos HTTP soportados.


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_uri
File name: twbs_jaxrs_defresource_uri.html