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:
REST API for Content Delivery, which is used to query and load any CMS asset that’s been published. Depending on the channel used to publish the content, this may or may not require authentication.
REST API for Content Management, which is used for legacy preview support, but is better suited for modifying CMS content programmatically. It always requires authentication.
REST API for Content Preview, which is used for modern preview support and closely follows the layout of the REST API for Content Delivery. It always requires authentication.
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.
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 runningnpm run start
.If the application is running, then stop it. We’ll now proceed with configuring it to use the new preview support:
Open the .env file (located in the root directory of the application).
Add the following lines to the file:
=TRUE PREVIEW='{ "previewClientAPI": "previewREST" }' OPTIONS
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:
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.
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:
.use('/content/', (req, res) => {
serverconst client = getClient();
.getAuthorizationHeaderValue().then((authValue) => {
clienthandleContentRequest(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) {
.headers = { Authorization: authValue };
options
}
// define a function that writes the proxied content to the response
const writeProxyContent = (proxyResponse) => {
.writeHead(proxyResponse.statusCode, proxyResponse.headers);
res.pipe(res, {
proxyResponseend: 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:
It makes it easy to validate prototype content using the same code base as the production environment.
It doesn’t require a large amount of development work to integrate it.
If the application uses dotenv in a similar way to the React blog, then it can be switched between delivery and preview using environment variables. This will ease any future orchestration development.
If the application already uses the legacy preview support, then it just needs to pass a few new settings (such as the OPTIONS flag discussed above) when calling the Content SDK in order to select the new API. You shouldn’t need to make any changes to how you load and display asset content.
Switching to the newer preview from the existing model allows it to benefit from any future optimizations made to preview support.
Use Preview APIs in Headless Oracle Content Management Sites
F56467-01
April 2022
Copyright © 2021, 2022, Oracle and/or its affiliates.
Primary Author: Oracle Corporation