Customize the Content HAL API Add-on

Info: Bloomreach provides Enterprise support for this feature for Bloomreach Experience customers. The release cycle for this feature may differ from the core product release cycle.

Extension Options

The default Content HAL APIs cover most use cases. However, the Content HAL API Add-on includes extension points for customization.

Overriding Spring Assembly Beans

Content HAL API Add-on services are defined in Spring bean assembly XML files located at classpath*:META-INF/hst-assembly/addon/com/onehippo/cms7/addon/halapi/*.xml.

To customize a built-in service bean, override its definition in an assembly XML file under classpath*:META-INF/hst-assembly/overrides/addon/com/onehippo/cms7/addon/halapi/*.xml. Only override these beans if you are familiar with Spring bean configuration.

Changing Default Parameters (e.g., Page Size)

The default page size for the API is 10. Callers can override this at runtime using the _limit query parameter, as described in the Content HAL Add-on documentation. If you need to change the default value when the caller does not provide _limit, you can override the halRestApiServiceQueryStringReplacingInterceptor bean in a custom assembly XML file (for example, classpath*:META-INF/hst-assembly/addon/com/onehippo/cms7/addon/halapi/custom-hal-params.xml):

<?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.xsd">

  <bean id="halRestApiServiceQueryStringReplacingInterceptor"
        class="org.hippoecm.hst.jaxrs.cxf.QueryStringReplacingInterceptor">
    <property name="paramNameReplaces">
      <map>
        <!--
        The following will replace '_format' parameter name with '_type'
        <entry key="_format" value="_type" />
        -->
      </map>
    </property>
    <property name="additionalQueryString">
      <value></value>
      <!--
      The following will set _limit parameter to 100 by default.
      <value>_limit=100</value>
      -->
      <!--
      Or the following will append additional query string before JAX-RS processing
      <value>addparam1=value1&amp;addparam2=value2</value>
      -->
    </property>
  </bean>

</beans>

The halRestApiServiceQueryStringReplacingInterceptor bean enables you to replace or append query parameters:

To replace parameter names at runtime, add entries to the paramNameReplaces property. For example, to allow both pageSize and _limit as query parameters, add <entry key="pageSize" value="_limit" />. Clients can then use either parameter to set the page size.
To set a default query string, use the additionalQueryString property. For example, setting _limit=100 will default the page size to 100 unless the caller specifies _limit. If a caller provides _limit, that value takes precedence because the additional query string is appended to the URI.

Customizing HAL Resource JSON Output

To add custom properties, metadata, or embedded resources to the returned HAL Resource JSON objects, implement a custom JcrContentHalResourceProcessor:

public MyCustomHalResourceProcessor implements JcrContentHalResourceProcessor {

    @Override
    public boolean isProcessable(Node contentNode) {
        // Add the 'externalSource' property only for nodes of type 'myproject:externallysourced'.
        return contentNode.isNodeType("myproject:externallysourced");
    }

    @Override
    public ContentHalResource process(ContentHalResource resource, Node contentNode) {
        // Add the 'externalSource' property to the resource.
        // You can also enrich the resource with data from external sources if needed.
        resource.setProperty("externalSource", JcrUtils.getStringProperty(contentNode, "myproject:externalsource", "");
    }
}

Info: The isProcessable(...) method is available since v2.0.2. In earlier versions, include such conditions in the process(...) method.

To register your custom JcrContentHalResourceProcessor, define it in a custom Spring assembly XML file under classpath:META-INF/hst-assembly/overrides/addon/com/onehippo/cms7/addon/halapi/. The bean ID must be customContentHalResourceProcessors.

For example, create site/components/src/main/resources/META-INF/hst-assembly/overrides/addon/com/onehippo/cms7/addon/halapi/custom-hal-processors.xml:

<?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="customContentHalResourceProcessors"
        class="org.springframework.beans.factory.config.ListFactoryBean">
    <property name="sourceList">
      <list>
        <bean class="com.example.hal.MyCustomHalResourceProcessor">
        </bean>
      </list>
    </property>
  </bean>
</beans>

Adding a Custom Plain JAX-RS Service

To add a new plain JAX-RS service, create a Spring bean assembly XML file under classpath:META-INF/hst-assembly/overrides/addon/com/onehippo/cms7/addon/halapi/, for example:
site/components/src/main/resources/META-INF/hst-assembly/overrides/addon/com/onehippo/cms7/addon/halapi/custom-extra-plain-jaxrs.xml.

Add your custom JAX-RS service beans (such as com.example.hal.jaxrs.service.MyExtraCustomJaxrsResource) to the customHalRestApiResourceProviders ListFactoryBean. The bean ID must be customHalRestApiResourceProviders.

<?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">

  <!-- Default empty list of custom plain resource providers to be overridden. -->
  <bean id="customHalRestApiResourceProviders"
    class="org.springframework.beans.factory.config.ListFactoryBean">
    <property name="sourceList">
      <list>
        <bean class="org.apache.cxf.jaxrs.lifecycle.SingletonResourceProvider">
          <constructor-arg>
            <bean class="com.example.hal.jaxrs.service.MyExtraCustomJaxrsResource">
            </bean>
          </constructor-arg>
        </bean>
      </list>
    </property>
  </bean>
</beans>

If your custom JAX-RS service bean uses a different path annotation at the class level, it will be available at that path. For example, you can add a custom JAX-RS service bean to handle document creation or updates using POST requests.