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.
<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
Résultats
Vous avez défini des opérations valides pour les ressources.