Définition des modèles d'identificateur URI des ressources dans les applications RESTful

Les services REST (Representational State Transfer) reposent sur la manipulation des ressources. Les ressources des services RESTful sont adressables et les URL constituent la principale méthode d'accessibilité dans REST.

Avant de commencer

Identifiez les ressources dans l'application à exposer comme service RESTful.

Pourquoi et quand exécuter cette tâche

Les URL sont utilisées pour définir l'emplacement d'une ressource. L'interaction entre le serveur et le client repose sur l'envoi d'opérations HTTP aux URL. La définition des modèles d'URL est importante, car les URL ont généralement une longue durée de vie pour que les clients puissent accéder à une ressource bien après sa détection.

Les URL sont généralement utilisées lorsque vous entrez des adresses dans des navigateurs web, telles que http://www.ibm.com/ ou http://www.example.com/bookstore/books/ISBN123. Bien que les URL n'aient pas besoin d'être comprises par les utilisateurs, les services RESTful qui fournissent des URL logiques dans des modèles compréhensibles permettent aux développeurs d'applications client de travailler efficacement.

Les clients RESTful utilisent des URL pour manipuler les ressources. Chaque ressource doit avoir sa propre URL unique. Certains modèles d'URL ont un chemin de collection avec un identificateur unique ajouté. Par exemple, vous pouvez utiliser http://www.example.com/bookstore/books comme URL de ressource de collection, http://www.example.com/bookstore/books/ISBN123 comme URL de ressource de livre unique et http://www.example.com/bookstore/books/ISBN123/authors pour extraire une ressource de collection décrivant les auteurs ISBN123.

Le développeur de l'application doit tenir soigneusement compte de la granularité des URL, car elle peut affecter l'utilisation et les performances de l'application. Par exemple, vous pouvez inclure les informations d'auteur d'un livre dans la ressource book ou les informations d'auteur sous la forme d'une ressource unique avec sa propre URL référencée dans la ressource book. Selon la réutilisation des ressources, il peut être plus efficace de définir une ressource distincte pour les information d'auteur référencées dans un lien hypertexe de la ressource book si l'auteur écrit un autre livre.

Lorsqu'une URL initiale est fournie à un client, les demandes associées suivantes sont détectables en analysant la syntaxe de la ressource en cours. Dans l'exemple de livre, une demande GET à http://www.example.com/bookstore/books/ extrait la liste des URL de livres pouvant inclure http://www.example.com/bookstore/books/ISBN123.

Etant donné que les systèmes reposent sur les ressources disponibles, les URL ont généralement une longévité. Du fait que HTTP dispose de codes d'état intégrés pour la redirection, tel que le code 301 de transfert permanent et le code 307 de redirection temporaire, les utilisateurs et les clients utilisant des caches réutilisent généralement les URL déjà découvertes. Vous pouvez également envisager d'inclure une version d'identificateur dans le modèle d'URL, telle que http://www.example.com/bookstore/v2/books/ISBN123. Comme dans le cas de la planification de la définition d'une interface en utilisant du code Java™, veillez à choisir soigneusement vos modèles d'URL étant donné la longévité attendue.

Dans Java API for RESTful Web Services (JAX-RS), vous devez ajouter des annotations @Path aux fichiers classe Java ou les méthodes Java pour définir l'URL relative des la ressource. Vous pouvez utiliser de releveurs de coordonnés de sous-ressources JAX-RS et des méthodes de sous-ressource pour définir des ressources. Utilisez des paramètres, tels que le paramètre de chemin ou le paramètre de matrice, dans l'URL pour identifier la ressource.

La valeur dans l'annotation @Path définit la partie relative de l'URL complète dans la ressource. L'URL de base est issue du domaine, du port de la racine de contexte du module d'application et des mappages de modèles d'URL dans le fichier web.xml file du module d'application. Par exemple, si le domaine est www.example.com, le port, 9060, la racine de contexte du module, example, le modèle d'URL de servlet, store/* et la valeur de l'annotation @Path, /bookstore/books, l'URL complète est http://www.example.com:9060/example/store/bookstore/books.

Procédure

  1. Identifiez les types de ressources dans l'application. Supposons que vous disposiez de deux types de ressources, de la collection de livres BooksCollection et d'un objet Livre individuel ayant les définitions de classe suivantes :
    public class BooksCollection {
            public BooksCollection() {
                    /* aucun constructeur d'argument */
        }
    
    }
    
    public class Book {
            public Book(String ISBN) {
                    /* Ce constructeur a un argument qui sera annoté avec une annotation JAX-RS.
             Voir la spécification JAX-RS pour plus d'informations sur les constructeurs valides. */
        }
    }
    Comme le définit la spécification JAX-RS, par défaut, des instances de ressource sont créées pour chaque demande.Pour que l'environnement d'exécution JAX-RS puisse créer une instance de ressource, vous devez disposer d'un constructeur sans argument ou d'un constructeur avec uniquement des paramètres annotés JAX-RS.
  2. Ajoutez une annotation @javax.ws.rs.Path à chaque classe de ressources.   Pour chaque annotation @javax.ws.rs.Path, définissez la valeur dans l'URL après l'URL de base de l'application.
    /*
     * BooksCollection.java
      * Cette classe java représente l'URL de la collection de livres à /bookstore/books.
     */
    @javax.ws.rs.Path("/bookstore/books/")
    public class BooksCollection {
    
    }
    Après avoir exécuté l'application, vous pouvez utiliser la ressource en visitant http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books. Pour cette URL, définissez la valeur de racine de contexte dans l'URL après le module de contexte. Définissez le chemin du servlet comme n'importe quels modèles d'URL dans le fichier web.xml, s'il existe.
  3. (Facultatif) Déterminez si une ressource doit utiliser une partie de l'URL comme paramètre. Si une ressource doit utiliser une partie de l'URL comme paramètre, telle que l'identificateur d'URL, vous pouvez utiliser l'annotation @javax.ws.rs.Path avec une expression régulière.Vous pouvez ensuite ajouter une annotation @javax.ws.rs.PathParam dans le constructeur de ressource ou la méthode de ressource.
    /*
      * Book.java represents individual books.
      */
    @javax.ws.rs.Path(“/bookstore/books/{bookID}”)
    public class Book {
           public Book(@javax.ws.rs.PathParam("bookID") String ISBN) {
    
       }
    }
    Lorsqu'une requête HTTP est envoyée à http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books/ISBN_number, une instance Book est créée avec ISBN_number envoyé au paramètre ISBN du constructeur.

    Pour plus d'informations sur les autres paramètres possibles, lisez les informations relatives à la définition des paramètres des demandes dans les ressources dans les applications RESTful.

  4. Créez la sous-classe javax.ws.rs.core.Application pour indiquer à l'environnement d'exécution JAX-RS les classes qui font partie de l'application JAX-RS. Les classes de ressources sont retournées dans la méthode getClasses(), par exemple :
    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;
        }
    }

    En définissant la sous-classe javax.ws.rs.core.Application, les classes retournées par ses méthodes sont enregistrées dans l'environnement d'exécution JAX-RS. Lorsque vous configurez le fichier web.xml, vous devez définir la sous-classe javax.ws.rs.core.Application comme paramètre dans le servlet ou le filtre. Pour plus d'informations, consultez les informations relatives à la configuration du fichier web.xml des applications JAX-RS.

Résultats

Vous avez créé une URL pour identifier vos ressources pour votre service RESTful. En traitant les problèmes de modèles d'URL dès le début de la conception de l'application, vous améliorez l'utilisation et la valeur du service RESTful dans le temps.

Que faire ensuite

La ressource à l'URL définie existe. Toutefois, la ressource ne dispose pas encore de méthodes pour gérer les actions de méthodes HTTP, telles que GET, POST, PUT ou DELETE. Voir la définition des méthodes de ressource des applications RESTful pour plus d'informations sur les fonctions de définition des ressources en utilisant des méthodes HTTP.


Icône indiquant le type de rubrique Rubrique de tâche



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_uri
Nom du fichier : twbs_jaxrs_defresource_uri.html