CDN APIs for Hybrid Implementations

A phased headless rollout is a technique for delivering a single shopping experience using multiple storefront technologies like Storefront Reference Architecture (SFRA) and Composable Storefront.

An embedded CDN (eCDN) zone can route traffic to both SFRA and Managed Runtime (MRT) at the same time, allowing you to gradually roll out a Composable Storefront.

This guide describes how to use Commerce API CDN Zones to route traffic to Managed Runtime. You can also use Business Manager to route traffic to Managed Runtime. See Configure MRT Routing Rules in Business Manager.

Before running the commands in this guide, replace any placeholders with actual values. Placeholders are formatted like this: $PLACEHOLDER.

Throughout this guide we use an example storefront with the production URL https://www.example.com.

Only existing customers can access some of the links on this page. Visit Salesforce Commerce Cloud GitHub Repositories and Access for information about how to get access to the Commerce Cloud repositories.
  1. Familiarize yourself with Authorization for Admin APIs
  2. You must have an Account Manager API Client with the scope sfcc.cdn-zones.rw.
  3. You must know the zone ID of the eCDN zone to be used with Managed Runtime. To get this info, use the getZonesInfo endpoint of the CDN Zones API.
  4. Use updateSecuritySettings to enable alwaysUseHttps on the zone. Managed Runtime only supports traffic over HTTPS.
  5. Set your SLAS API Client’s redirect_uri to include the zone.
  6. If you have restricted the set of IPs allowed to access your Managed Runtime environment, add the CloudFlare IPs used by eCDN to the set of allowed IPs.

With the createMrtRules endpoint, you can create rules that route traffic to a Managed Runtime environment:

Let’s examine the data provided in the request body.

The value of mrtHostname is the domain of the Managed Runtime environment for traffic routing. It must refer to a Managed Runtime environment hosted on the mobify-storefront.com domain. If the provided value is used by an existing rule, the request fails.

Managed Runtime is the only supported routing destination.

The value of expressions is an array of Cloudflare rule expressions that controls which requests are routed to Managed Runtime. For most implementations, a single routing expression is sufficient.

In addition to the provided expressions, the following default routing rules are used:

Routing changes are applied immediately, and navigating to a URL that matches an expression returns content retrieved from Managed Runtime.

  • The following routing scenarios are supported:

    • A single hostname mapped to a single MRT environment:

      • For example, http.host eq \"www.example.com\" → example-production.mobify-storefront.com

    • Multiple hostnames mapped to a single MRT environment:

      • For example, http.host in {\"www.example.com\" \"prod.example.com\" \"us.example.com\"}→ example-production.mobify-storefront.com

  • The following routing scenario is currently not supported:

    • A single hostname mapped to multiple MRT environments based on different paths

Expressions are validated against the following criteria:

  • http.host must occur exactly once and must be followed by either the eq or in operator. See above for usage examples.
  • The hostname(s) must match the zone. Or in other words, the eCDN zone must have a valid certificate that covers the provided hostname(s).
  • The following fields are supported:
    • http.host
    • http.request.uri.path
    • http.request.uri
    • http.cookie
  • The maximum length of an expression is 3072 characters.
  • A maximum of 100 expressions can be associated with a zone.

As you continue your phased rollout, you can route more requests to Managed Runtime.

To modify a routing expression, use getMrtRules to get the IDs of the ruleset and rule associated with the expression you want to update:

Next, use updateMrtRule to update the expression:

To add more routing rules to an existing Managed Runtime environment, use updateMrtRuleset and provide the mrtHostname and additional routing expressions:

To add routing rules for a new Managed Runtime environment, use the createMrtRules endpoint and provide a new mrtHostname value:

To update existing rules to route to a different Managed Runtime environment, use updateMrtRuleset and provide the oldMrtHostname and the (new) mrtHostname that you want to route to:

If you're switching to a third-party CDN or you no longer want to route a particular path from eCDN to MRT, you can disable routing.

To disable routing, use getMrtRules to get the IDs of the configuration that you want to delete:

Then, to remove the Managed Runtime routing rule, use deleteMrtRule and pass in the applicable IDs returned by getMrtRules:

If you want to remove all Managed Runtime routing rules, use deleteMrtRuleset:

When you complete your phased rollout or if you are launching a new site, you can choose to route all traffic for a zone to Managed Runtime using a single expression:

On environments where eCDN is not available, use the composable-hybrid-dev-server to simulate eCDN routing.