Servicios REST (Representational State Transfer)

REST (Representational State Transfer) es una infraestructura ligera para diseñar aplicaciones que utilizan HTTP para realizar llamadas. REST utiliza HTTP para realizar operaciones Create, Read, Update y Delete (CRUD) entre cliente y servidor. Las aplicaciones interactúan con los servicios utilizando operaciones HTTP, POST, PUT, GET y DELETE.

HCL Commerce utiliza servicios de Transferencia de Estado Representacional (REST - Representational State Transfer) para proporcionar una infraestructura que se puede utilizar para desarrollar aplicaciones RESTful en varias plataformas. Estas plataformas pueden incluir aplicaciones web, móvil, quioscos y sociales.

Comparativamente, REST puede realizar las mismas funciones que SOAP (Simple Object Access Protocol) y que WSDL (Web Services Description Language).

REST es una plataforma independiente del idioma y dado que está basada en HTTP, es compatible en entornos protegidos mediante cortafuegos. REST puede utilizar conexiones seguras a través de HTTPS para aprovechar las características de seguridad HTTPS como las señales de cifrado o nombre de usuario y contraseña.

Las llamadas REST incluyen toda la información necesaria para devolver resultados (de transferencia de estado), lo que elimina la necesidad de cookies cuando se utilizan los servicios REST en el escaparate.

Los servicios REST ayudan a facilitar la invocación de mandatos de controlador clásicos y la activación de los beans de datos. Pretender proporcionar una infraestructura que es fácil de leer y personalizar. La infraestructura le permite crear manejadores de recursos REST personalizados que invocan mandatos de controlador para realizar operaciones de adición, actualización y supresión, o activar beans de datos para recuperar datos.
Importante: No se recomienda utilizar la infraestructura de programación clásica de REST para invocar los mandatos de controlador que cambian información de sesión. Por ejemplo, el ID de usuario. Los mandatos de controlador de ejemplo que alteran la información de sesión son los mandatos LogonCmd y LogoffCmd.

Puede crear servicios REST utilizando el mandato de controlador basado en configuración y la infraestructura de correlación de beans de datos. Ayuda a crear servicios REST y automatiza las correlaciones utilizando el programa de utilidad restClassicSampleGen y permite la activación de beans de datos o la ejecución de mandatos de controlador utilizando servicios REST.

API de REST disponible

Características de los servicios REST

La lista siguiente resume las características clave de la arquitectura REST:
  • Utiliza un sistema cliente-servidor.
  • Carece de estado.
  • Soporta almacenamiento en memoria caché de recursos.
  • Se da soporte a servidores proxy.
  • Utiliza URL lógicos para identificar recursos.

Abstracción de los servicios REST

El siguiente diagrama ilustra los diversos componentes de la abstracción de los servicios REST:
Diagrama de la abstracción de los servicios REST
Donde:
  • Los Proveedores de contexto incorporados buscan ciertos elementos en la solicitud, como el ID de tienda, el ID de idioma o la identidad de usuario. Los Proveedores de contexto utilizan estos elementos para crear el contexto adecuado que se utiliza para recuperar o actualizar el Documento de objeto de negocio (BOD) en HCL Commerce. Los proveedores de contexto primarios son:
    • Proveedor de contexto de negocio
    • Proveedor de contexto de seguridad
    Estos proveedores de contexto se invocan para cada solicitud y proporcionan contexto, según corresponda, a los manejadores e recursos.
  • Los Manejadores de recursos representan los puntos de entrada para las solicitudes de recursos y se anotan con la vía de acceso, el contexto y cualquier otra información que puedan necesitar para manejar una solicitud. Los manejadores de recursos se encargan de coordinar la solicitud y la respuesta BOD y de convertir la solicitud y la respuesta a y desde un formato que pueda consumir el cliente utilizando elementos del protocolo HTTP estándar. También son responsables de las representaciones de recursos compuestos en las que hay más de un BOD u origen integrados. Además, los manejadores de recursos también son responsables de asegurar que los recursos relacionados estén identificados y especificados correctamente en la representación.

    Cada manejador de recursos implementa la interfaz com.ibm.commerce.foundation.rest.resourcehandler.IResourceHandler. Puede personalizar un manejador de recursos sustituyendo sus métodos.

  • Los Ayudantes ayudan a los manejadores de recursos a establecer un puente con la capa de BOD y permiten un código común reutilizable entre los manejadores. También hay ayudantes para almacenar configuración, construir los URI y para aplicar los requisitos de seguridad de transporte que se especifican para los manejadores de recursos.
  • Los Correlacionadores de datos son archivos de configuración que se utilizan para transformar representaciones de recursos a y desde atributos BOD. Esto le permite personalizar de forma declarativa la representación.
  • Los Proveedores de entidades predeterminados permiten la codificación estándar de las respuestas en formato JSON o XML en función de los correlacionadores de datos. Puede añadir sus propios proveedores personalizados para otros tipos de soporte que se adapten a las necesidades de su empresa.
  • Las Plantillas de recursos son un mecanismo para permitirle representar representaciones personalizadas, tales como XHTML, utilizando un archivo JSP.

Servicios REST en HCL Commerce

Se pueden desarrollar aplicaciones RESTful en varias plataformas para HCL Commerce. El siguiente diagrama ilustra las diversas plataformas de clientes REST y servidores:
Plataformas de clientes REST y servidores
Donde:
Aplicaciones móviles
Los servicios REST permiten el desarrollo de aplicaciones móviles que aprovechan las interfaces de usuario nativas específicas de la plataforma de dispositivos, o un navegador web integrado para la experiencia del usuario y servicios REST para datos y actualizaciones.
Aplicaciones web
Las aplicaciones web pueden incluir escaparates tradicionales, o funciones web específicas que proporcionan la funcionalidad de HCL Commerce mediante servicios REST. La cantidad de interacciones entre cliente web y servidor puede variar con los servicios REST que caracterizan a estas aplicaciones.
Las aplicaciones web in situ indican que la aplicación (o parte de la aplicación) se ejecuta en el servidor de HCL Commerce.
Aplicaciones sociales
Estas aplicaciones se representan dentro de contenedores sociales, como Facebook. Las aplicaciones sociales pueden ampliar las experiencias de compra y del cliente.
Las aplicaciones web in situ indican que la aplicación (o parte de la aplicación) se ejecuta en el servidor de HCL Commerce.
Aplicaciones de quiosco/escritorio
Estas aplicaciones aprovechan servicios de HCL Commerce para conectar los compradores de ubicación de tienda con la tienda y servicios en línea.

Interacción de servicios REST

El siguiente diagrama muestra el flujo de la interacción de servicios REST:
Diagrama de flujo de interacción de servicios REST
Donde:
Servicios de autenticación:
  1. Autentica un usuario registrado o crea un usuario invitado.
  2. Invoca una solicitud de servicio de miembro.
  3. Devuelve una identidad autenticada.
  4. Crea señales de autenticación.
  5. Devuelve las señales WCToken y WCTrustedToken.
  6. Genera una respuesta en el formato solicitado.
  7. Devuelve un objeto de respuesta al cliente.
Servicios de negocio:
  1. Crea una solicitud de servicio con señales de seguridad.
  2. Invoca manejadores de solicitudes y BCS.
  3. Verifica las señales de seguridad según el tiempo de ejecución.
  4. Correlaciona recursos de JAX-RS con servicios de componentes de HCL Commerce, genera y envía solicitudes de servicio.
  5. Devuelve el resultado como objeto de datos de servicio (SDO).
  6. Correlaciona el SDO con el formato de datos solicitado.
  7. Devuelve el objeto de respuesta al cliente.
Mandato y servicios de beans de datos:
  1. Crea una solicitud de servicio con señales de seguridad.
  2. Invoca manejadores de solicitudes y BCS.
  3. Verifica las señales de seguridad según el tiempo de ejecución.
  4. Correlaciona recursos de JAX-RS con:
    • Mandatos de controlador de HCL Commerce para ejecutar el mandato.
    • Beans de datos de HCL Commerce para realizar la activación de beans de datos.
  5. Devuelve los resultados en:
    • TypedProperty por mandato de controlador.
    • TypedPropertypor manejador de recursos.
  6. Devuelve el objeto de respuesta al cliente.

    Los formatos de respuesta JSON y XML se soportan de forma predeterminada.

Parámetros generales de consulta

Además de los parámetros de consulta especificados en cada API de servicio REST, hay disponibles los parámetros de consulta opcionales siguientes para todos los servicios REST. El URL de solicitud REST puede incluir uno o más parámetros, si es necesario:
responseFormat
El formato de respuesta de la solicitud. De forma predeterminada, se da soporte a los formatos JSON y XML. Los valores de responseFormat son xml o json. El valor predeterminado es json.

JSON es el único formato de respuesta soportado por la API REST de búsqueda de WebSphere Commerce de forma predeterminada. Por ejemplo, en los recursos CategoryViewHandler, ProductViewHandler y SiteContentHandler indicado por (Search).

Los formatos de respuesta JSON y XML se soportan de forma predeterminada.

Para los formatos personalizados, utilice letras en minúscula para el valor de formato de respuesta. Por ejemplo, responseFormat=custom.

El formato de respuesta de la solicitud se determina utilizando la siguiente precedencia: el parámetro de consulta responseFormat en la URL, y luego el encabezado de solicitud HTTP Accept. En caso contrario, json es el formato de respuesta predeterminado.

langId
El ID de idioma utilizado durante la consulta. Si no se especifica, se utiliza el ID de idioma predeterminado de la tienda.
langId tiene prioridad sobre locale al determinar qué lenguaje utiliza la respuesta de REST, donde locale se utiliza como reserva cuando no se especifica langId.
entorno nacional
El entorno local de la solicitud.
Por ejemplo, locale=en_US para inglés de EE.UU.
langId tiene prioridad sobre locale al determinar qué lenguaje utiliza la respuesta de REST, donde locale se utiliza como reserva cuando no se especifica langId.
currency
La moneda que se utiliza para mostrar valores monetarios en los datos de canal de información.
Por ejemplo, currency=USD para dólares estadounidenses.
catalogId
El ID de catálogo utilizado durante la consulta. Si no se especifica, se utiliza el ID de catálogo predeterminado de la tienda.
forUser
El nombre de usuario de la solicitud.
Consulte la descripción del parámetro forUserId.
forUserId
El ID de usuario de la solicitud.
Los parámetros de entrada de URL forUser y forUserId REST le permiten especificar que el mandato se ejecute para el usuario especificado, incluso si el usuario que ha iniciado la sesión actualmente sea diferente. Esto es especialmente útil cuando un representante de servicio al cliente necesita ayudar a un cliente. Por ejemplo, el representante de servicio al cliente puede actualizar la dirección de un cliente en nombre de dicho cliente, especificando el nombre de usuario o el ID de usuario del cliente mediante el uso de los parámetros de entrada de REST. Este cambio en la información de usuario solo es válido durante el tiempo que dura la petición de URL para la que se ha especificado. El parámetro forUser es el valor del ID de conexión del usuario. El parámetro forUserId es el valor del ID del usuario.
Nota:
  • Para utilizar el parámetro REST forUserId, primero debe realizar una GET /person/@self?forUserId=userIdllamada independiente, para que la actividad se configure correctamente.
  • Si LDAP se ha configurado como depósito de usuarios que debe utilizarse con HCL Commerce, se debe utilizar el nombre distinguido completo para este parámetro forUser.
  • El usuario representado por forUser o forUserId no debe ser un administrador. Además, el administrador que ejecuta el mandato debe poder administrar al usuario. Asimismo, el administrador debe tener el rol adecuado en la organización actual de la tienda, o en alguna de las organizaciones predecesoras. La política de control de acceso que especifica qué administradores y mandatos pueden utilizar los parámetros forUser y forUserId es: BecomeUserCustomerServiceGroupExecutesBecomeUserCmdsResourceGroup De forma predeterminada, el usuario predeterminado debe tener uno de los siguientes roles para realizar la operación forUser o forUserId.
    • Representante de servicio al cliente
    • Supervisor de servicio al cliente
    • Seller
    • Director de ventas
    • Director de operaciones
    • Administrador de sitio
workspace.name
Nombre del espacio de trabajo a utilizar.
workspace.taskGroup
Identificador del grupo de tareas en el espacio de trabajo.
workspace.task
Identificador de la tarea en el espacio de trabajo.

Limitaciones

Tenga en cuenta las limitaciones siguientes cuando se trabaja con la API de REST de HCL Commerce:
  • Revise los servicios REST disponibles para asegurarse de que la funcionalidad que está implementando está disponible. Por ejemplo, los códigos de promoción no están admitidos de forma predeterminada cuando se utilizan servicios REST en los flujos previos a pasar por caja y pasar por caja del carro.
  • Los servicios REST están diseñados principalmente para funcionar con la tienda de inicio Aurora.
  • Los manejadores de API de REST dependen de que la búsqueda de HCL Commerce funcione correctamente, ya que los servicios de búsqueda utilizan la navegación de catálogo basada en la búsqueda. Debe habilitar la búsqueda de HCL Commerce o personalizar los servicios REST para que se adapten a sus necesidades empresariales cuando trabaja con estos manejadores.
  • La compresión de datos no está soportado por omisión, ya que podría provocar errores de búsqueda en el escaparate.
  • Las API de REST que se correlacionan con los servicios BOD no pueden manejar determinados caracteres especiales debido a la forma en que se analiza XPath. Cuando se encuentran caracteres especiales, se devuelve un código de error de servidor interno 500, porque la infraestructura de BOD no maneja la excepción para devolver un código de error de respuesta distinto. Para evitar este problema, no utilice caracteres especiales como <, >, y , ' o " en las API de REST que se correlacionan con servicios BOD.

HCL Commerce API REST

HCL Commerce Los servicios REST son servicios REST JAX-RS basados en Apache Wink. Las clases de implementación contienen anotaciones JAX-RS, tales como @Path, @Produces, @Consumes, @QueryParam y @PathParam.