Technical design

This page discusses the following technical design topics of the Content REST API:

• Access control and CORS
• Configuration options
• Adding to project not using Essentials
• API versioning
• Relationship to manual resources
• XML output

Access control and CORS

The default setup of the Content REST API is such that it exposes all content under the project’s content folder to all clients. In case more control is needed, it is possible to:

• Control which content is exposed by configuring a different content root for the API.
• Configure different CORS settings; the default settings allow all clients from all addresses to access the API. See the configuration section below.

At the moment there is no out-of-the-box mechanism to add authentication / authorization to the Content REST API resources. Contact us in case this is necessary in your project.

Configuration options

At the moment, the only two configuration options that should be considered API for projects are the following two beans:

• restApiCorsFilter: to set a different CORS filter
• maxSearchResultItems: to set a different maximum for the page size; the default is 100; requests that send in a higher _max query parameter will have their _max capped this this maximum; setting a higher maximum must be done with caution in order not to run into issues with the BundleCache

To override these beans, create the following file:

<yourproject>/site/components/src/main/resources/META-INF/hst-assembly/overrides/addon/org/hippoecm/hst/restapi/restapi-overrides.xml

And add for example:

<?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="maxSearchResultItems" class="java.lang.Integer">
    <constructor-arg value="50" />
  </bean>
​</beans>

The other Spring wiring is subject to change. Contact us in case overriding the other Spring wiring is necessary in your project.

Adding to project not using Essentials

It is supported to add the Content REST API resources to a project that does not use Essentials. As the Content REST API has been developed as an HST Addon Module adding the resource is no more work than adding a new mount to the HST configuration of the project. As an example the following setup:

API versioning

The Content REST API does not yet provide functionality to automatically version the API. Projects that require a versioned API can add for instance v1 to the URL through configuration of the HST mount point.

Relationship to manual resources

It is possible to use the Content REST API resources side-by-side with other JAXRS resources, especially with resources that are generated by Essentials through the REST setup tool. The “REST Services setup” tool enables you to set up both mechanisms. By default, the Content REST API (the generic REST resources) use a different pipeline than the “manual” resources. The Content REST API uses "RestApiPipeline" and the manual resources use "JaxrsRestPlainPipeline" for backward compatibility reasons. The main differences are:

• CORS settings: RestApiPipeline does set CORS headers, JaxrsRestPlainPipeline does not (both allow custom configuration)
• Cache control settings: RestApiPipeline does not set any cache control headers so it is easier for proxies to add this explicitly, JaxrsRestPlainPipeline sets explicit "do-not-cache" headers, see noCacheResponseHeadersValve.

XML output

At the moment, the Content REST API only supports JSON output. In case XML output is necessary, the advice is to use manual resources.