Définitions des méthodes de ressource des applications RESTful

Les ressources individuelles peuvent définir leurs fonctions en utilisant des méthodes HTTP prises en charge. Dans les services REST (Representational State Transfer), les méthodes prises en charge sont GET, PUT, DELETE et POST. Toutes les opérations sont généralement exécutées en utilisant l'une des méthodes HTTP prédéfinies avec une ressource.

Avant de commencer

Connaître les méthodes HTTP prédéfinies et leurs attributs connus. Certaines méthodes HTTP sont réputées fiables, à savoir que l'émission d'une demande ne change pas la ressource ou idempotent, ce qui implique que plusieurs appels de l'opération ne change pas le résultat. Bien que les méthodes HTTP soient définies pour avoir certains attributs, l'implémentation des services suit les définitions. Voir les informations relatives aux définitions des méthodes HTTP pour en savoir plus sur les groupes de méthodes courantes pour HTTP.

Pourquoi et quand exécuter cette tâche

Les clients utilisent des méthodes HTTP pour exécuter certaines opérations. Contrairement aux autres système répartis où des interfaces uniques sont définies par chaque système, les systèmes RESTful basés sur HTTP reposent principalement sur des méthodes prédéfinies. Les quatre méthodes les plus courantes sont GET, PUT, DELETE et POST. Aucune ressource n'est nécessaire pour autoriser tous les méthodes HTTP pour tous les clients.

La méthode HTTP GET extrait une représentation de ressource. Elle est fiable et idempotent. Des demandes GET répétitives ne changent pas les ressources.

La méthode HTTP PUT est généralement utilisée pour mettre à jour des ressources ou pour créer une entité à une URL connue. Lorsqu'une ressource doit être mise à jour ou créée, une méthode HTTP PUT est émise à l'URL de ressource avec les données de la nouvelle ressource comme entité de demande, appelée également corps de message. La méthode HTTP PUT étant idempotent, plusieurs demandes PUT identiques avec la même entité vers la même URL génère le même résultat que l'émission d'une seule demande. Cette méthode suppose qu'aucune autre demande pertinente n'a été émise.

La méthode HTTP DELETE supprime une ressource à une URL spécifique.

La méthode HTTP POST est généralement utilisée pour créer une ressource dans une collection lorsque l'URL de ressource finale est inconnue. Par exemple, un administrateur émet une demande POST vers une ressource de collection /users qui crée un utilisateur avec un ID unique, tel que 1234567890. L'ID unique est utilisé ensuite dans le chemin d'URL pour décrire la nouvelle ressource utilisateur, telle que /users/1234567790. Elle n'est pas fiable ni idempotent. Dans ce cas, plusieurs demandes POST vers la collection /users peuvent continuer de créer un ID unique et d'ajouter ce nouvel ID à la collection d'utilisateurs, même si l'utilisateur a les mêmes informations.

Etant donné que la plupart des services RESTful utilisent des méthodes HTTP connues qui fournissent le résultat attendu, vous pouvez créer plus aisément des clients. Les développeurs de services RESTful peuvent tirer parti des comportements attendus des méthodes HTTP. Les méthodes de ressource peuvent également utiliser des paramètres, tels que des paramètres de chemin, des paramètres de requête ou des paramètres de matrice pour identifier la ressource. Consultez les informations relatives à la définition de l'utilisation des paramètres pour les représentations de requêtes dans les ressources pour plus d'informations.

(Facultatif) Si vous avez une méthode de sous-ressource et une méthode de localisateur de sous-ressource ayant une annotation @Path avec la même valeur de la même classe de ressource, le localisateur de sous-ressource n'est pas considéré lors de la détermination de la méthode à appeler par défaut. C'est conforme aux spécifications JAX-RS.

Utilisez la propriété wink.searchPolicyContinuedSearch avec une valeur de true pour modifier ce comportement. Ceci entraîne l'utilisation des localisateurs de sous-ressources si aucune méthode de sous-ressource ne correspond à la requête.

Pour activer la propriété, incluez un fichier de propriétés dans le répertoire WEB-INF du module avec la propriété wink.searchPolicyContinuedSearch et la valeur spécifiées. Dans le fichier web.xml du module d'application, incluez un élément init-param avec la valeur propertiesLocation pour l'élément param-name. L'élément param-value spécifie l'emplacement du fichier de propriétés, par exemple WEB-INF/my_wink.properties.

L'exemple suivant illustre le fichier web.xml :
<servlet>
    ...
    ...
    <init-param>
        <param-name>propertiesLocation</param-name>
        <param-value>/WEB-INF/my_wink.properties</param-value>
    </init-param>
</servlet>
L'exemple suivant illustre le fichier de propriétés WEB-INF/my_wink.properties :
wink.searchPolicyContinuedSearch=true

Dans l'exemple de code suivant, l'URL de demande se termine par sayhello, mais la demande contient une méthode POST au lieu d'une méthode GET, si bien que le message d'erreur HTTP 405 Method Not Allowed est renvoyé. Vérifiez que la méthode HTTP envoyée correspond à l'annotation de méthode pour éviter le message d'erreur 405.

@javax.ws.rs.Path("helloworld")
public class SampleResource {

...

@javax.ws.rs.Path("sayhello")
@javax.ws.rs.GET
public String getHello() { ...

Procédure

  1. Identifiez les types de ressources dans l'application.
    Pour chaque classe de ressources, identifiez une méthode existante ou créez une méthode à appeler pour chaque méthode HTTP prise en charge.Les méthodes qui répondent aux requêtes HTTP s'appellent également des méthodes de ressource.Pour chaque méthode de ressource dans la classe de ressources, annotez la méthode Java™ avec une seule annotation de méthode HTTP JAX-RS, telle que @javax.ws.rs.GET, @javax.ws.rs.POST, @javax.ws.rs.DELETE ou @javax.ws.rs.PUT.Par exemple, si une méthode HTTP GET est prise en charge par la classe BooksCollection, vous pouvez créer et annoter une méthode comme suit :
    @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;
        }
    }
    Lorsque vous émettez une demande HTTP GET vers l'URL http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books en utilisant un navigateur Web ou un autre client HTTP, la méthode getBooksCollection() précédente est appelée.
  2. Vérifiez que la ressource prend en charge les méthodes HTTP nécessaires.
    Chaque ressource a généralement plusieurs méthodes de ressource, par exemple :
    @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. */
        }
    }
    Lorsque vous émettez une demande HTTP GET vers l'URL http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books/<isbn_number> en utilisant un navigateur web ou un autre client HTTP, la méthode retrieveSpecificBookInformation() est appelée.L'envoi d'une requête HTTP PUT à la même URL appelle la méthode updateBookInformation et le contenu dans le corps de message de la demande est envoyé sous la forme de la valeur de l'objet updatedBookInfo.Enfin, l'envoi d'une requête HTTP DELETE à la même URL appelle la méthode removeBook().
    Eviter les incidents Eviter les incidents: Selon la spécification JAX-RS, vous ne devez pas placer plusieurs annotations de méthode HTTP, telles que @javax.ws.rs.POST ou @javax.ws.rs.PUT, dans la même méthode de ressource. Etant donné que les méthodes HTTP ont des sémantiques définies de manière unique, n'utilisez pas une méthode de ressource pour plusieurs méthodes HTTP.gotcha

Résultats

Vous avez défini des opérations valides pour les ressources.


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_httpmeth
Nom du fichier : twbs_jaxrs_defresource_httpmeth.html