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) is available for Primary Instance Group (PIG) environments, such as production or staging, and can route traffic to both SFRA and Managed Runtime (MRT) at the same time, allowing you to gradually roll out a Composable Storefront. Secondary Instance Group (SIG) environments, such as an on-demand sandbox (ODS) or a local development server, don't have an eCDN. In this case, use hybrid proxy to route traffic to SFRA.

For SIG instances, such as an ODS or a local development server, develop and test hybrid shopper apps that use PWA Kit and SFRA or SiteGenesis by enabling the hybrid proxy feature in the pwa-kit-runtime package in PWA Kit v3.14.0 and later.

For more information, see Step 2: Set Up Hybrid Locally (SIG Instances) in Hybrid Authentication.

For PIG instances, an eCDN zone can route traffic to both SFRA and MRT at the same time, allowing you to gradually roll out a Composable Storefront.

This diagram shows the sequence of requests and responses when an eCDN routes an incoming page request for a hybrid app for a PIG instance. If the request matches MRT rules, it is forwarded to MRT. Otherwise, if the request doesn't match MRT rules, it is sent to the B2C Commerce instance, and then a response is returned.

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.

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 or exp-delivery.com domain. If the provided value is used by an existing rule, the request fails.

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 300 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:

• Hybrid Implementation Guidance
• Hybrid Authentication