Use Preview APIs in Headless Oracle Content Management Sites

Introduction

This tutorial describes how to add support for the new REST API for Content Preview in Oracle Content Management applications that use the Oracle Content SDK. Adding this functionality makes it easy for content creators to view their new content in the same application that’s used to render their production work. It also opens the door to using orchestration to handle both production and prototype versions of the application with minimal changes to the build process.

Note that while previous versions of the Content SDK supported a preview mode, it was based on a different server-side REST interface that wasn’t optimized for the task. Switching to the newer API isn’t difficult and will help future-proof your applications.

The sections below provide some details about what changes were made to the Content SDK, describe how to modify a sample project, the React blog sample, to support the new preview API, and finally how to obtain and use OAuth parameters.

This tutorial focuses on React, but you can use a similar approach for other web technologies including Angular, Gatsby, Next.js, Svelte, and Vue.js.

Changes in the Oracle Content SDK

The Oracle Content SDK is a JavaScript library that provides convenient wrappers around Oracle Content Management REST API calls. It allows applications to search for and retrieve both published and preview assets from the server without having to make direct REST calls. In this context, a published asset is a piece of content that’s been made public while a preview asset is information that’s still in development or may be public sometime in the future. A published asset may be made available with or without requiring authentication, while a preview asset always requires authentication.

When using the Content SDK, an application will create an instance of a content client, either contentDeliveryClient (for published content) or contentPreviewClient (for preview content). In earlier versions of the Oracle Content SDK, there was only one preview interface available. This was a wrapper that used the REST API for Content Management of the server to perform its queries. While this did work, it wasn’t an optimal solution since that REST API was really designed for other purposes. Because of this, a second interface was introduced: the REST API for Content Preview. This can now be selected as an alternative when creating a preview client in the Oracle Content SDK.

Rest APIs Used by the Content SDK

These are the REST APIs that the Content SDK uses internally:

How to Configure the React Blog Application to Use the New Preview API

We’ll use the React blog sample as a base for this tutorial. Note that it uses the dotenv library, which allows you to change build parameters using environment variables. This is valuable because it allows the application to be switched from published to preview mode with no changes to the internal code.

  1. First, you’ll need to install and build the React blog sample. At the end of this step, you should have an application that can be built by running npm run build and executed by running npm run start.

  2. If the application is running, then stop it. We’ll now proceed with configuring it to use the new preview support:

    1. Open the .env file (located in the root directory of the application).

    2. Add the following lines to the file:

      PREVIEW=TRUE    
OPTIONS='{ "previewClientAPI": "previewREST" }'

    The first entry, PREVIEW, is used to tell the application to run in preview mode.

    The second entry, OPTIONS, specifies that we want to use the REST API for Content Preview for preview mode. Alternately, the previewClientApi option could have been set to managementREST, but that should only be used for legacy support.

How to Set the OAuth Parameters for Preview Mode

To complete the configuration of the blog application, we need to configure the OAuth parameters needed to authenticate to the server. This can take one of two forms:

  1. A bearer token string that’s set in the .env file as follows:

     AUTH=Bearer xxxxxx

    where xxxxxx is the OAuth token of your application.

    This option is quick and convenient if you already have a valid OAuth token string that you can use. However, it has a limitation in that the token may only be valid for a certain period of time and the application will start failing once the token has expired. This brings us to the second option, which has a more complex setup, but can retrieve new tokens as the existing ones expire.

  2. Provide an object in the .env file with the following format:

    AUTH_PARAMS='{ "CLIENT_ID": "aaa", "CLIENT_SECRET": "bbb", "CLIENT_SCOPE_URL": "ccc", "IDP_URL": "ddd" }'

    The IDP_URL parameter is the URI of your identity prover. It may be Oracle Identity Cloud Service (IDCS) or Identity Access Management (IAM) when used with Oracle Content Management.

The Oracle Content Management documentation provides details on how to configure a client application and how to get these parameter values.

If both AUTH and AUTH_PARAMS are specified, then AUTH_PARAMS takes precedence.

Special Handling of Preview Security in the React Blog Sample

Depending on which JavaScript framework is used and how an application is written, it may perform its content retrieval and page generation entirely on the server side, entirely on the client side, or a mixture of both. In the case of the React blog sample and other headless CMS samples, it was decided that secure content retrieval should always happen on the server side so that the client side wouldn’t have to know anything about the security configuration settings. For this reason, the clients were modified to redirect what would be direct calls to the content management system back to the server side of the application, which would then be responsible for retrieving and returning the content.

A simple example of this can be seen when loading the home page of the React blog application. When loading the page in a browser, the server sends a prebuilt page populated with all the text content. All images, though, are provided as URLs to be loaded by the web browser directly from Oracle Content Management. This would require the web browser to make authenticated calls, which is something that we don’t want it to do. The solution is to have the code intercept such calls and redirect them back to the NodeJS application serving up the application.

In the case of the React blog application, the code that redirects direct calls to the content management system to the server side can be found in /src/server/server.js.

First, the express server providing the server-side support has the following redirect code:

server.use('/content/', (req, res) => {
  const client = getClient();
  client.getAuthorizationHeaderValue().then((authValue) => {
    handleContentRequest(req, res, authValue);
   });
 });

And that in turn calls:

function handleContentRequest(req, res, authValue) {
  // only proxy GET requests, ignore all other requests
  if (req.method !== 'GET') {
    return;
  }

  // build the URL to the real server
  let content = process.env.SERVER_URL.charAt(process.env.SERVER_URL.length - 1) === '/'
    ? 'content' : '/content';
  if (req.url.charAt(0) !== '/') {
    content = `${content}/`;
  }
  const oceUrl = `${process.env.SERVER_URL}${content}${req.url}`;

  // Add the authorization header
  const options = {};
  if (authValue) {
    options.headers = { Authorization: authValue };
  }

  // define a function that writes the proxied content to the response
  const writeProxyContent = (proxyResponse) => {
    res.writeHead(proxyResponse.statusCode, proxyResponse.headers);
    proxyResponse.pipe(res, {
      end: true,
    });
  };

Conclusion

Adding preview support to your Oracle Content Management application is a simple way to increase the flexibility and value of your product. Some of the benefits that this brings include: