Services REST

Representational State Transfer (REST) est une structure légère pour la conception d'applications qui utilisent HTTP pour passer des appels. REST utilise HTTP pour effectuer les opérations Créer, Lire, Mettre à jour et Supprimer (CRUD) entre le client et le serveur. Les applications interagissent avec les services à l'aide des opérations HTTP, POST, PUT, GET et DELETE.

HCL Commerce utilise les services REST (Representational State Transfer) pour fournir une structure qui permet de développer des applications RESTful sur plusieurs plateformes. Ces plateformes peuvent inclure des applications Web, mobiles, de bornes d'information et sociales.

Comparativement, REST peut effectuer les mêmes fonctions que Simple Object Access Protocol (SOAP) et Web Services Description Language (WSDL).

REST ne dépend d'aucune plateforme et d'aucune langue et, parce qu'il est construit sur HTTP, il est compatible dans les environnements derrière les pare-feu. REST peut utiliser des connexions sécurisées sur HTTPS pour exploiter les fonctions de sécurité HTTPS telles que le chiffrement ou le nom d'utilisateur et les jetons de mot de passe.

Les appels REST incluent toutes les informations nécessaires pour renvoyer les résultats (transfert d'état), éliminant ainsi la nécessité de disposer de cookies lorsque vous utilisez les services REST dans la vitrine.

Les services REST facilitent l'appel des commandes de contrôleurs classique et l'activation des beans de données. Ils visent à fournir une structure facile à apprendre et à personnaliser. La structure vous permet de créer des gestionnaires de ressources REST personnalisés qui invoquent des commandes de contrôleur pour effectuer des opérations d'ajout, de mise à jour et de suppression, ou pour activer des beans de données afin de récupérer des données.

Important : Il n'est pas recommandé d'utiliser la structure de programmation classique REST pour appeler les commandes de contrôleur qui modifient les informations de session. Par exemple, l'ID utilisateur. Les commandes LogonCmd et LogoffCmd sont des exemples de commandes de contrôleur qui modifient les informations de session.

Vous pouvez créer des services REST à l'aide de la structure de mappage de la commande de contrôleur et des beans de données basée sur la configuration. Ils permettent de créer des services REST et automatisent les mappages à l'aide de l'utilitaire restClassicSampleGen, et permettent l'activation de beans de données ou l'exécution de commandes de contrôleur à l'aide des services REST.

API REST disponible

API REST administrative pour la gestion des organisations de votre site, des rôles d'utilisateur et de la mondialisation.
API REST de vitrine pour la gestion des données de magasin et transactionnelle, telles que pour la gestion des catalogues, le marketing, les commandes, les prix, la recherche, et plus encore.
(externalized customization) API REST de point d'extension pour vous aider à créer une logique métier personnalisée afin d'étendre les processus par défaut ou d'appeler des processus personnalisés.

Caractéristiques des services REST

La liste suivante résume les principales caractéristiques de l'architecture REST :

Utilise un système client-serveur.
Sans état.
Prend en charge la mise en cache des ressources.
Les serveurs Proxy sont pris en charge.
Utilise des URL logiques pour identifier les ressources.

Abstraction des services REST

Le diagramme suivant illustre les différents composants de l'abstraction des services REST :
Diagramme d'abstraction des services REST

Où :

La recherche Fournisseurs de contexte intégrée recherchent certains éléments dans la requête tels que l'ID de magasin, l'ID de langue ou l'identité de l'utilisateur. Les fournisseurs de contexte utilisent ces éléments pour générer le contexte approprié utilisé pour récupérer ou mettre à jour le BOD (Business Object Document) dans HCL Commerce. Les principaux fournisseurs de contexte sont les suivants :
- Fournisseur de contexte d'entreprise
- Fournisseur de contexte de sécurité
Ces fournisseurs de contexte sont appelés pour chaque requête et fournissent le contexte approprié aux gestionnaires de ressources.
Les gestionnaires de ressources représentent les points d'entrée pour les requêtes de ressources et sont annotés avec le chemin d'accès, le contexte et toute autre information dont ils pourraient avoir besoin pour traiter une requête. Les gestionnaires de ressources sont responsables de la coordination de la requête et de la réponse de la BOD et de la conversion de la requête et de la réponse en un formulaire consommable par le client à l'aide d'éléments de protocole HTTP standard. Ils sont également responsables de la représentation des ressources composites lorsque plus d'une BOD ou d'une source sont intégrés. De plus, les gestionnaires de ressources sont également responsables de s'assurer que les ressources connexes sont correctement identifiées et spécifiées dans la représentation.
Chaque gestionnaire de ressources implémente l'interface com.ibm.commerce.foundation.rest.resourcehandler.IResourceHandler. Vous pouvez personnaliser un gestionnaire de ressources en remplaçant ses méthodes.
Les auxiliaires aident les gestionnaires de ressources à faire le lien avec la couche BOD et permettent de réutiliser un code commun entre les gestionnaires. Il existe également des auxiliaires pour la configuration du magasin, la génération d'URI et l'application des exigences de sécurité de transport qui sont spécifiées pour les gestionnaires de ressources.
Les mappeurs de données sont des fichiers de configuration utilisés pour transformer les représentations de ressources vers et depuis les attributs BOD. Cela vous permet de personnaliser de manière déclarative la représentation.
Les fournisseurs d'entités par défaut permettent l'encodage standard des réponses en tant que format JSON ou XML basé sur des mappeurs de données. Vous pouvez ajouter vos propres fournisseurs personnalisés pour d'autres types de support en fonction de vos besoins métier.
Les modèles de ressources sont un mécanisme qui vous permet d'afficher des représentations personnalisées telles que XHTML à l'aide d'un fichier JSP.

Services REST dans HCL Commerce

Les applications RESTful peuvent être développées sur plusieurs plateformes pour HCL Commerce. Le diagramme suivant illustre les différentes plateformes et différents serveurs clients REST :
Plateformes et serveurs du client REST

Où :

Applications mobiles: Les services REST permettent le développement d'applications mobiles qui exploitent des interfaces utilisateur natives spécifiques à la plateforme du périphérique, ou un navigateur Web intégré pour l'expérience utilisateur et les services REST pour les données et les mises à jour.
Applications Web: Les applications Web peuvent inclure des vitrines traditionnelles ou des fonctionnalités Web spécifiques qui fournissent une fonctionnalité HCL Commerce via les services REST. La quantité d'interactions avec les clients et le serveur Web peut varier avec les services REST qui caractérisent ces applications.; Les applications Web sur site indiquent que l'application (ou qu'une partie de l'application) s'exécute sur le serveur HCL Commerce.
Applications sociales: Ces applications sont affichées dans des conteneurs sociaux tels que Facebook. Les applications sociales peuvent étendre les achats et les expériences clients.; Les applications sociales sur site indiquent que l'application (ou une partie de l'application) s'exécute sur le serveur HCL Commerce.
Applications kiosque/bureau: Ces applications tirent parti des services HCL Commerce afin d'associer les clients de l'emplacement de magasin au magasin en ligne et aux services.

Interaction des services REST

Le diagramme suivant montre le flux d'interaction des services REST :
Diagramme du flux d'interaction des services REST

Où :

Services d'authentification :

Authentifie un utilisateur enregistré ou crée un utilisateur invité.
Invoque une requête de service membre.
Renvoie une identité authentifiée.
Crée des jetons d'authentification.
Renvoie les jetons WCToken et WCTrustedToken.
Génère une réponse dans le format demandé.
Renvoie un objet de réponse au client.

Services professionnels :

Effectue une requête de service avec des jetons de sécurité.
Invoque les gestionnaires de requêtes et BCS.
Vérifie les jetons de sécurité par exécution.
Mappe les ressources JAX-RS aux services composants HCL Commerce, génère et envoie des requêtes de service.
Renvoie le résultat en tant que SDO ( Service Data Object).
Mappe le SDO au format de données demandé.
Renvoie l'objet de réponse au client.

Services de commande et de bean de données :

Effectue une requête de service avec des jetons de sécurité.
Invoque les gestionnaires de requêtes et BCS.
Vérifie les jetons de sécurité par exécution.
Mappe les ressources JAX-RS :
- HCL Commerce aux commandes de contrôleur pour effectuer la commande.
- HCL Commerce aux beans de données pour effectuer l'activation des beans de données.
Renvoie les résultats :
- TypedProperty par commande de contrôleur.
- TypedProperty par gestionnaire de ressources.
Renvoie l'objet de réponse au client.
Les formats de réponse JSON et XML sont pris en charge par défaut.

Paramètres de requête généraux

Outre les paramètres de requête spécifiés dans chaque API de service REST, les paramètres de requête facultatifs suivants sont disponibles pour tous les services REST. L'URL de demande REST peut inclure un ou plusieurs paramètres de requête, si nécessaire :

responseFormat

Format de réponse de la demande. Les formats JSON et XML sont pris en charge par défaut. Les valeurs possibles pour responseFormat sont xml ou json. La valeur par défaut est json.

JSON est le seul format de réponse pris en charge par l'API REST de recherche WebSphere Commerce par défaut. Par exemple, dans les ressources CategoryViewHandler, ProductViewHandler et SiteContentHandler indiquées par (Recherche).

Les formats de réponse JSON et XML sont pris en charge par défaut.

Pour les formats personnalisés, utilisez des lettres minuscules pour la valeur du format de réponse. Par exemple, responseFormat=custom.

Le format de réponse de la requête est déterminé à l'aide de la priorité suivante : le paramètre de requête responseFormat dans l'URL, puis l'en-tête de requête HTTP Accept. Sinon, json est le format de réponse par défaut.

langId

ID langue utilisé durant la requête. S'il n'est pas spécifié, l'ID langue par défaut est utilisé.

langId est prioritaire sur le paramètre régional lors de la détermination de la langue utilisée par la réponse REST, où le paramètre régional est utilisé comme repli lorsque langId n'est pas spécifié.

locale

Environnement local de la demande.

Par exemple, locale=en_US pour l'anglais américain.

monétaire

Devise utilisée pour afficher les valeurs de devise dans les données de flux.

Par exemple, currency=USD pour les dollars américains.

catalogId

ID catalogue utilisé au cours de la requête. S'il n'est pas spécifié, l'ID catalogue de magasin par défaut est utilisé.

forUser

Nom d'utilisateur de la demande.

Voir la description du paramètre forUserId.

forUserId

ID utilisateur de la demande.

Les paramètres REST forUser et forUserId vous permettent de spécifier que la commande doit être exécutée pour l'utilisateur spécifié, même si l'utilisateur qui est actuellement connecté peut être différent. Ceci est particulièrement utile lorsqu'un représentant du service clientèle doit aider un client. Par exemple, le représentant du service clientèle peut mettre à jour l'adresse d'un client au nom de ce client en spécifiant le nom d'utilisateur ou l'ID d'utilisateur du client à l'aide des paramètres REST. Cette modification des informations utilisateur n'est valable que pour la durée de la requête URL pour laquelle elle a été spécifiée. Le paramètre forUser est la valeur de l'ID de connexion de l'utilisateur. Le paramètre forUserId est la valeur de l'ID d'utilisateur de l'utilisateur.

Remarque :

Pour utiliser le paramètre REST forUserId, vous devez d'abord effectuer un appel GET /person/@self?forUserId=userId distinct pour que l'activité soit correctement définie.
Si LDAP est configuré comme référentiel utilisateur à utiliser avec HCL Commerce, le DN complet doit être utilisé comme valeur pour ce paramètre forUser.
L'utilisateur représenté par forUser ou forUserId ne doit pas être un administrateur. L'utilisateur doit également être gérable par l'administrateur qui exécute la commande. En outre, l'administrateur doit jouer le rôle approprié dans l'organisation du magasin actuel, ou l'une de ses organisations ancêtres. La stratégie de contrôle d'accès qui spécifie les administrateurs et les commandes qui peuvent utiliser les paramètres forUser et forUserId est la suivante : BecomeUserCustomerServiceGroupExecutesBecomeUserCmdsResourceGroup. Par défaut, l'utilisateur administratif doit disposer de l'un des rôles suivants pour effectuer l'opération forUser ou forUserId :
- Représentant du service clientèle
- Responsable du service clientèle
- Seller
- Responsable des ventes
- Gestionnaire des opérations
- Administrateur de site

workspace.name: Nom de l'espace de travail à utiliser.
workspace.taskGroup: Identificateur du groupe de tâches dans l'espace de travail.
workspace.task: Identificateur de la tâche dans l'espace de travail.

Limitations

Considérez les limitations suivantes lorsque vous utilisez l'API REST HCL Commerce :

Examinez les services REST disponibles pour vous assurer que les fonctionnalités que vous implémentez sont disponibles. Par exemple, les codes de promotion ne sont pas pris en charge par défaut lorsque vous utilisez les services REST pour les flux de prépaiement et de paiement du panier.
Les services REST sont principalement conçus pour fonctionner avec le magasin type Aurora.
Les gestionnaires d'API REST s'appuient sur HCL Commerce Search pour fonctionner correctement, car les services de recherche utilisent la navigation de catalogue basée sur la recherche. Vous devez activer HCL Commerce Search ou personnaliser les services REST en fonction de vos besoins métier lorsque vous utilisez ces gestionnaires.
La compression des données n'est pas prise en charge par défaut, car elle peut entraîner des erreurs de recherche dans la vitrine.
Les API REST mappées aux services BOD ne peuvent pas gérer certains caractères spéciaux en raison de la façon dont le chemin XPath est analysé. Lorsque des caractères spéciaux sont rencontrés, un code d'erreur de serveur interne 500 est renvoyé, car la structure BOD ne gère pas l'exception pour renvoyer un code d'erreur de réponse différent. Pour éviter ce problème, n'utilisez pas de caractères spéciaux tels que <, >, &, ' ou " dans les API REST mappées aux services BOD.

HCL Commerce API REST

HCL Commerce Les services REST sont des services REST JAX-RS créés par-dessus Apache Wink. Les classes d'implémentation contiennent des annotations JAX-RS, telles que @Path, @Produces, @Consumes, @QueryParam et @PathParam.