Configure API Agent Channel - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 12. There's an updated version available that covers our most recent release.

Configure API Agent Channel

BloomReach offers Enterprise support for this feature to BloomReach Experience customers. The release cycle of this feature may differ from our core product release cycle. 

Introduction

As an API Agent Channel captures personalization variant configurations on behalf of a Plain JAX-RS Services mount, the HST-2 request processing pipeline on the specific Plain JAX-RS Services mount needs to resolve the associated API Agent Channel at runtime in order to read personalization variant configurations for the JAX-RS Services.

By default, the associated API Agent Channel for a Plain JAX-RS Services mount is automatically inferred by appending "-agent" to the resolved Plain JAX-RS Services mount path. For example, if the resolved REST API mount in a request is "/restapi", then "/restapi-agent" will be used, by default, to resolve the associated API Agent Channel. This can be changed by setting an optional property, @hst:mountagentmountpath, on the resolved Plain JAX-RS Services mount configuration if the mount path of the associated API Agent Channel is different from this default mount path mapping pattern.

Conversely, the API Agent Channel in Channel Manager also needs to know the specific Plain JAX-RS Services mount path and its Swagger API Documentation URL for some user actions. e.g, "Open Swagger UI" button. These settings are configured through the Channel Settings window of the API Agent Channel.

Channel Settings of API Agent Channel

In an API Agent Channel, you can change settings through Channel Settings window.

The settings are provided with some default values.

Here is the detail of each Channel Setting parameter:

 Parameter Name  Description  Default value
 API Mount Path  The Plain JAX-RS Services mount path for which this Agent Channel serve.  /restapi
 API Swagger Document Path  The Swagger Documentation Path Info, which must be after the API Mount Path.
 For example, if the Swagger Documentation URI is /site/restapi/swagger.yaml (where /site is the context path and /restapi is the mount path), just take /swagger.yaml after the mount path to configure this parameter.
 /swagger.yaml
 Swagger UI URI  The Swagger UI web application URI. This is used to open Swagger UI in the API Agent Channel page.
 For example, if you have installed a Swagger UI web application as with /api-docs context path onto the servlet container, just take the context path and append a slash for this parameter.
 /api-docs/

REST API Mount Property

When a request comes onto the Plain JAX-RS Services mount, the request processing pipeline needs to resolve the API Agent Channel at runtime, in order to read personalization variant parameters. By default, the mount of the associated API Agent Channel is inferred simply by appending "-agent" to the resolved Plain JAX-RS Services mount path. For example, if the resolved REST API mount is "/restapi", then "/restapi-agent" will be used automatically to resolve the associated Agent Channel.

However, sometimes you might want to use a different mount path for the API Agent Channel. In that case, you can specify the mount path of the API Agent Channel explicitly by setting an optional property, @hst:mountagentmountpath, on the Plain JAX-RS Services mount configuration.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?