Public Relevance REST API

Overview

The Public Relevance REST API exposes a visitor's personal data stored in the Relevance database. This API is part of the Bloomreach Content Relevance Module and supports GDPR compliance. For more information on GDPR support, see GDPR Support.

This page explains how to enable the Public Relevance REST API in your implementation project and how to extend the API with custom endpoints.

Enabling the Public Relevance REST API

After adding the Relevance Module to your project, the site module will include the following dependency through the hippo-addon-targeting-site-dependencies POM:

<dependency>
  <groupId>com.onehippo.cms7</groupId>
  <artifactId>hippo-addon-targeting-site-rest</artifactId>
</dependency>

This dependency provides the required components for the Public Relevance REST API. To make the API available, configure the hst:mount nodes for each host where you want to expose the REST API. You must configure REST mounts for every host that targets visitors, because the visitor cookie is host-specific.

Example: Relevance REST API Mount Configuration

Suppose your HST configuration includes the following structure:

/hst:hst:
  /hst:hosts:
    /prod:
      /com:
        /example:
          /www:
            /hst:root:
              jcr:primaryType: hst:mount
              /subsite:
      /org:
        /example:
          /www:
            /hst:root:
              jcr:primaryType: hst:mount
              /subsite:

This configuration defines two hosts, each with two channels:

If you target visitors on all channels, you must be able to serve their personal data on request to comply with GDPR. The Relevance REST API enables this functionality. Decide which URL path to use for the API; for example, /gdpr:

Update the HST configuration as follows:

/hst:hst:
  /hst:hosts:
    /prod:
      /com:
        /example:
          /www:
            /hst:root:
              jcr:primaryType: hst:mount
              /subsite:
                jcr:primaryType: hst:mount
              /gdpr:
                jcr:primaryType: hst:mount
                hst:ismapped: false
                hst:types: rest
                hst:namedpipeline: TargetingRestApiPipeline
      /org:
        /example:
          /www:
            /hst:root:
              jcr:primaryType: hst:mount
              /subsite:
                jcr:primaryType: hst:mount         
              /gdpr:
                jcr:primaryType: hst:mount
                hst:ismapped: false
                hst:types: rest
                hst:namedpipeline: TargetingRestApiPipeline

With this configuration, the Public Relevance REST API is available at /gdpr for each host.

By default, the API provides the /visitorinfo endpoint, which supports the following operations:

GET: Retrieve personal data for the current visitor. See Serve Personal Data.
DELETE: Request deletion of the visitor's data. See Forget About Me.

Extending the Public Relevance REST API

You can add new endpoints or override default endpoints from the TargetingRestApiPipeline by defining Spring beans in the following location within your project's site module:

META-INF/hst-assembly/overrides/addon/com/onehippo/cms7/targeting/restapi

Example: Adding a Custom Relevance REST API Endpoint

The following example demonstrates how to add a custom endpoint to the Relevance REST API. For instance, you may need to provide an endpoint that returns all visitor IDs with a last access time before the current time, with a configurable limit, and another endpoint to retrieve VisitorInfo for a specific visitor ID.

Configuration

Create a file named targeting-site-restapi-extension.xml in the directory shown above. The file can have any name.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans 
                           http://www.springframework.org/schema/beans/spring-beans-4.1.xsd">

  <bean id="com.hap.targeting.rest.LatestVisitorsResource" class="com.hap.targeting.rest.LatestVisitorsResource" init-method="init"/>

  <bean id="customRestApiResourceProviders" class="org.springframework.beans.factory.config.ListFactoryBean">
    <property name="sourceList">
      <list>
        <bean class="org.apache.cxf.jaxrs.lifecycle.SingletonResourceProvider">
          <constructor-arg>
            <ref bean="com.myproject.targeting.rest.LatestVisitorsResource"/>
          </constructor-arg>
        </bean>
      </list>
    </property>
  </bean>
</beans>

Implementation

Add the following Java class in the com.myproject.targeting.rest package:

package com.hap.targeting.rest;

import java.util.ArrayList;
import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;

import com.onehippo.cms7.targeting.VisitorInfo;
import com.onehippo.cms7.targeting.VisitorService;

import static javax.ws.rs.core.MediaType.APPLICATION_JSON;

@Path("/visitors")
@Produces(APPLICATION_JSON)
public class LatestVisitorsResource {

    private VisitorService visitorService;
    private final int DEFAULT_LIMIT = 10; 

    public void init() {
        this.visitorService = HippoServiceRegistry.getService(VisitorService.class);
    }

    @GET
    @Path("/")
    public List<String> getLatestVisitorsIds(@QueryParam("limit") final int limit) {
        final List<String> latestVisitorsIds = new ArrayList();
        visitorService
                .getLatestVisitors(System.currentTimeMillis(), limit == 0 ? DEFAULT_LIMIT : limit)
                .forEach(visitor -> latestVisitorsIds.add(visitor.getId()));
        return latestVisitorsIds;
    }

    @GET
    @Path("/{visitorId}/")
    @Produces(MediaType.APPLICATION_JSON)
    public VisitorInfo getVisitorDetails(@PathParam("visitorId") final String visitorId) {
            return visitorService.getVisitorInfo(visitorId);
    }

}

Usage

After deploying these changes and assuming the mount is named gdpr, you can access the new endpoints:

To retrieve the latest visitor IDs (default limit is 10):
```
http://www.example.com/gdpr/visitors
```
To retrieve visitor information for a specific visitor ID:
```
http://www.example.com/gdpr/visitor/{id}
```
Replace {id} with an actual visitor ID returned by the previous endpoint. The response will include the same data as the default Serve Personal Data endpoint.

Note: This example does not include security measures such as @RolesAllowed. In a production environment, implement appropriate security for all custom endpoints.