Structure du service REST distant pour PUMA

L'interface fournie par le service REST distant pour PUMA définit des opérations individuelles caractérisées par un chemin URI donné, la méthode HTTP, les données d'entrée ou de sortie attendus et une liste de paramètres de requête. En ce qui concerne le format d'entrée ou de sortie, l'interface décrit uniquement une base de référence commune pour la charge, qui peut être encapsulée ou représentée individuellement par différentes implémentations du service.

Structure du service REST distant

Tous les chemins d'URI définis par l'interface sont précédés du préfixe /um qui peut être considéré comme la partie identifiante du service. Les implémentations du service peuvent ajouter des éléments au chemin avant l'élément /um, par exemple pour représenter la racine de contexte d'un servlet. Par conséquent, les clients ne devraient pas supposer que le chemin complet du servlet débute toujours par /um.

Les chemins d'URI débutant par /um/secure ne seront suivis que dans un contexte utilisateur valide, c'est à dire uniquement dans une demande authentifiée. Si l'élément /secure est omis dans le chemin, l'opération est réalisée dans le contexte de l'utilisateur anonyme. Par souci de simplicité, la description de l'interface mentionne tous les chemins d'URI sans l'élément /secure. Cependant, toutes les opérations correspondantes peuvent être effectuées aussi bien pour l'utilisateur authentifié que pour l'utilisateur anonyme. Dans le cas d'opérations associées à des utilisateurs authentifiés, il vous faut ajouter en préfixe l'élément /secure. Ceci implique également que l'implémentation spécifique de l'interface doit veiller à l'application des vérifications de contrôle d'accès appropriées avant d'exécuter une opération.

Les parties hébergeant des variables dans les chemins d'URI et les paramètres de requête peuvent contenir des caractères spéciaux. Elles doivent être codées de sorte à présenter des éléments de chemin ou des paramètres valides. L'interface spécifie l'utilisation du code UTF-8 par le client et dans les URL renvoyées par le serveur.

Certaines opérations de l'interface peuvent utiliser des opérations HTTP PUT et DELETE mais, pour des raisons de sécurité, de nombreux environnements permettent uniquement l'utilisation d'opérations GET ou POST dans les requêtes HTTP. Pour sa compatibilité avec de tels scénarios, l'interface définit un mécanisme de remplacement global des opérations PUT et DELETE par des requêtes POST :

Paramètre de requête postAction avec une valeur put ou delete. Le cas est ignoré.
Paramètre de requête X-Method-Override avec une valeur put ou delete. Le cas est ignoré.

L'implémentation doit rendre possible l'activation ou la désactivation de cette tunnellisation des méthodes de requête en cas de besoin. Pour chaque opération, vous pouvez spécifier le format d'entrée et de sortie. Pour ce faire, vous pouvez utiliser la paramètre de requête mime-type ou l'en-tête de requête accept comme défini dans la spécification HTTP RFC 2616. Si vous utilisez le paramètre de requête, les informations de l'en-tête d'acceptation sont ignorées.