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

The API Agent Channel Add-on enables a seamless integration with Relevance Module for the Plain JAX-RS Services in your project. This module depends on the automatic Swagger API documentation support feature by a Spring bean configuration, as described in Plain JAX-RS Services.

Problem

When your HST-2 based application is only responsible for REST APIs serving content from the backend CMS (so-called "Headless Scenario" or "Content-as-a-Service" approach), it is very hard to achieve a seamless integration with Relevance Module in the REST APIs because of the following reasons:

The personalization feature of Relevance Module depends on component configurations (see Personalize a Component page for detail). In contrast, the REST API with Plain JAX-RS Services cannot be associated with a channel directly. The Plain JAX-RS Services is just configured at a specific mount without any associated channel having pages and components. As no component configuration can be associated with a JAX-RS REST Service by default, you cannot configure different personalization variants through component configurations for the Plain JAX-RS Services.
Due to this limitation, some workaround solutions were experimented before. For example, some developers tried to implement their REST Services by writing JSON outputs manually in each HST template (*.ftl) pages and aggregating those JSON output in the whole page response. This kind of workaround approaches make it more difficult to develop and maintain REST Services because this approach doesn't adopt the JEE and industry standard such as JAX-RS and it doesn't take advantage of POJO-based mapping/binding which is provided by most JAX-RS frameworks.

Solution

The solution is to let business users configure personalization variants through Delegate Components in an Agent Channel for a Plain JAX-RS Services mount. See the following diagram.

Suppose you have already set up a Plain JAX-RS Services mount (e.g, /restapi/**). As the REST API mount cannot be directly associated with a channel (containing page and component configurations) by itself, this solution provides a way to create an Agent Channel for the REST API mount. An API Agent Channel can have a page and component configurations on behalf of the REST API mount. For each JAX-RS Service, the API Agent Channel provides a Delegate Component which is created automatically and capturing personalization variant configurations on behalf of the JAX-RS Service.

In summary,

Developers can create an API Agent Channel for a Plain JAX-RS Services mount.
Business users can use the API Agent Channel to configure personalization variants per JAX-RS Service class, and they can publish the API Agent Channel to apply the changes.
At runtime, when requests are coming onto the Plain JAX-RS Services mount (e.g, /restapi/**), the API Agent Channel Add-on module resolves the API Agent Channel and reads personalization variant parameters captured through Delegate Components ("AC!DC") for the specific JAX-RS service. So, the specific JAX-RS service can read the personalized parameters through @ParametersInfo annotation and @Context ParametersInfoProvider parameter as explained in RESTful JAX-RS Component Support in HST-2. API Agent Channel Add-on module enables this under the hood by injecting some internal valves into the Plain JAX-RS Service Pipeline.

Installation and Configuration

For installation, please see Install page for details. Also, there are some configurations basically about how to associate an API Agent Channel with a Plain JAX-RS Services mount. Please see Configuration page for details.

You can also find the latest releases in the Release Notes page.

Demo Project

Download Demo Project

Please visit the following page to download a Demo project package ZIP file (Note: you need a BloomReach Experience Developer account to download):

https://maven.bloomreach.com/#browse/browse:maven2-enterprise:com%2Fonehippo%2Fcms7%2Fhippo-addon-api-agent-channel

You can find a proper version of the demo project for you and download the ZIP artifact.

Build / Run Demo Project

After extracting the ZIP file to a folder locally, you can build and run the demo project as follows:

$ cd hippo-addon-api-agent-channel-demopkg-x.x.x
$ mvn clean package && mvn -Pcargo.run

About the Demo

The demo project was created through Bloomreach Experience Manager Maven Archetype, and converted to a Bloomreach Experience Manager project.
For demonstration purpose, two simple features were added through Essentials: News and Events.
Also, for demonstration purpose, custom REST API Services for News (http://localhost:8080/site/restapi/NewsDocument/**) and Events (http://localhost:8080/site/restapi/EventsDocument/) were added through Essentials as well:
Automatic Swagger Documentation generation was configured through a Spring bean configuration as explained in RESTful API Support - Plain JAX-RS Services.
Finally, the API Agent Channel add-on was installed.

Demo Scenario

Log in to http://localhost:8080/cms/.
Select Experience manager, and click on "Add Channel" button to create a new API Agent Channel for the /restapi mount.
Select "API Agent Channel Add-on Blueprint", and click on "Next..." button.
In the "Name" field, enter something like "My REST API Agent Channel".
In the "URL" field, enter "http://localhost/restapi-agent".
In "Content Root" field, select any document folder, and click on "Create Channel" button. NOTE: Please make sure to select a valid folder! Otherwise the API Agent Channel cannot be displayed.
Now, you will see an "AC!DC" channel in "api-agent" channel category.
Click on the "AC!DC" channel you've just created.
Try to click on the "Open Swagger UI" button and confirm the popup dialog. You will see the auto-generated Swagger Documentation through the demo Swagger-UI in a separate browser tab.
Also you can click on the "Try out" button in the "GET /EventsDocument". You will see three results by default as Essentials created three Events documents during the setup.
Go back to the Experience manager. You don't see any Delegate Components for the REST services yet.
Now, click on "Reload API Management Infos" button, and confirm the popup dialog.
You will see two Delegate Components now. One for "EventsDocument" JAX-RS Service and the other for "NewsDocument" JAX-RS service that you've seen in the Swagger UI.
Edit the "EventsDocument" Delegate Component and enter "food" in the "api.tags" parameters (under the "Filter" group).
Save and close the Delegate Component parameter setting dialog, and publish the API Agent Channel.
Now, select the Swagger UI in a spearate browser tab, and click on "Try out" in the "GET /EventsDocument" again. This time, you will see only one result having "food" tag in the event document as there is only one Events document with "food" tag in CMS.