Configure a CDN host for a channel

Introduction

Goal

Serve images and assets through a CDN by configuring a CDN host for your channel.

Background

Images and assets uploaded to a Bloomreach Content environment can be accessed through the Delivery API for use in frontend applications. By default they are served from your Bloomreach Content environment's domain (*.bloomreach.io).

It's possible (and recommended) to serve images and assets through a CDN by configuring a CDN host for a channel. The Delivery API uses the configured CDN host for any resource URL referenced in the JSON representations in the API responses.

Configure a CDN host using the Site Management API

The CDN host can be configured per channel through its cdnHost property (also see the Channel schema) using the Site Management API's Channels endpoint.

The supported CDN host format is:

//{cdnhost}

For example, if you want binaries to be served from cdn.example.org, configure:

"cdnHost": "//cdn.example.org",

Other formats like //cdn.acct.example.org or //cdn.acct.example.org:8080 are also supported. Scheme prefixes such as http or https are supported as well although not recommended.

Example channel JSON

Below is an example Site Management API channel configuration with cdnHost set to //cdn.example.org:

{
    "id": "pacific-home-vJfh5",
    "name": "Pacific Home",
    "projectName": "CDN Example",
    "projectState": "UNAPPROVED",
    "branch": "vJfh5",
    "branchOf": "pacific-home-",
    "externalPreviewEnabled": false,
    "externalPreviewToken": "3c0f70b9-dff5-4a5f-9bd8-17bcc0a6848f",
    "contentRootPath": "/content/documents/pacific-home",
    "locale": "en_US",
    "devices": [],
    "defaultDevice": null,
    "responseHeaders": null,
    "linkurlPrefix": null,
    "cdnHost": "//cdn.example.org",
    "remoteHostProtection": false,
    "parameters": {
        "discoveryAccountId": "${public.brx.smAccountId}",
        "graphql_baseurl": "${public.brx.graphql.baseurl}",
        "discoveryRealm": "PRODUCTION",
        "graphqlTenantName": "${public.brx.graphql.tenantName}",
        "externalLocale": "en_US",
        "discoveryDomainKey": "${public.brx.smDomainKey}",
        "discoveryViewId": "",
        "spaUrl": "${public.brx.reference.spa.baseurl:https://brxm-react-spa.herokuapp.com/}"
    }
}

Example Delivery API response

Below is an example Delivery API image set representation containing resource URLs using the configured CDN host:

"udb02dde500984488a72c2a4fc6d51beb" : {
      "type" : "imageset",
      "links" : { },
      "meta" : { },
      "data" : {
        "name" : "picture.jpeg",
        "displayName" : "picture.jpeg",
        "description" : null,
        "original" : {
          "name" : "hippogallery:original",
          "displayName" : "hippogallery:original",
          "width" : -1,
          "height" : -1,
          "lastModified" : 1236880917884,
          "mimeType" : "image/jpeg",
          "filename" : "picture_original.jpeg",
          "size" : 168981,
          "links" : {
            "site" : {
              "href" : "//cdn.exmaple.org/delivery/resources/unittestcontent/gallery/picture.jpeg",
              "type" : "resource"
            }
          }
        },
        "thumbnail" : {
          "name" : "hippogallery:thumbnail",
          "displayName" : "hippogallery:thumbnail",
          "width" : -1,
          "height" : -1,
          "lastModified" : 1236880917884,
          "mimeType" : "image/jpeg",
          "filename" : "picture_thumbnail.jpeg",
          "size" : 1490,
          "links" : {
            "site" : {
              "href" : "//cdn.example.org/delivery/resources/thumbnail/unittestcontent/gallery/picture.jpeg",
              "type" : "resource"
            }
          }
        },
        "fileName" : null,
        "localeString" : null,
        "id" : "db02dde5-0098-4488-a72c-2a4fc6d51beb"
      }
    }

Technical: Why should a CDN start with //

Per RFC3986 chapter 5.4.1:

Within a representation with a well defined base URI of

http://a/b/c/d;p?q

a relative reference is transformed to its target URI as follows.

RFC 3986                   URI Generic Syntax               January 2005
5.4.1.  Normal Examples

      "g:h"           =  "g:h"
      "g"             =  "http://a/b/c/g"
      "./g"           =  "http://a/b/c/g"
      "g/"            =  "http://a/b/c/g/"
      "/g"            =  "http://a/g"
      "//g"           =  "http://g"
      "?y"            =  "http://a/b/c/d;p?y"
      "g?y"           =  "http://a/b/c/g?y"
      "#s"            =  "http://a/b/c/d;p?q#s"
      "g#s"           =  "http://a/b/c/g#s"
      "g?y#s"         =  "http://a/b/c/g?y#s"
      ";x"            =  "http://a/b/c/;x"
      "g;x"           =  "http://a/b/c/g;x"
      "g;x?y#s"       =  "http://a/b/c/g;x?y#s"
      ""              =  "http://a/b/c/d;p?q"
      "."             =  "http://a/b/c/"
      "./"            =  "http://a/b/c/"
      ".."            =  "http://a/b/"
      "../"           =  "http://a/b/"
      "../g"          =  "http://a/b/g"
      "../.."         =  "http://a/"
      "../../"        =  "http://a/"
      "../../g"       =  "http://a/g"

Example 6 is the relevant one:

//g  =  http\://g

The advantage of // is that it follows the scheme (http or https) of the request that created the HTML in which references to binary files are added that need to be loaded from a CDN. This way, in the above example, when accessing http://www.example.org, all files are served from http://cdn.example.org and when accessing https://www.example.org, all files are served from https://cdn.example.org.