Proxy Requests

Managed Runtime's proxy feature allows you to route requests to APIs hosted on different domains through the same domain as your storefront.

Why use the same domain as your storefront? Imagine your storefront is hosted at www.northerntrailoutfitters.com and you want to request B2C Commerce API from api.commercecloud.salesforce.com. Making this request without proxying involves extra configuration steps and isn’t as fast and observable as it could be with proxying. Let’s compare the two approaches:

Now that you understand the value of using proxies, let’s explore the various methods for configuring them.

During local development proxies can be configured by editing the mobify.ssrParameters.proxyConfigs array in <PROJECT_DIR>/config/default.js. For example, to configure a proxy for the B2C Commerce API:

The proxyConfigs array contains objects that define a proxy configuration with the following properties:

• host: the origin host that receives your requests.
• path: the name used in the request path to identify this proxy.

To make a proxy request in your application code, follow this pattern when building request paths: /mobify/proxy/<PROXY_PATH>.

Let’s look at an example request that uses api as the path value. By default, projects created with PWA Kit include proxy configuration that associates the api path with the B2C Commerce API.

When you change proxy configuration during local development, you must restart your local development server for the changes to take effect.

Managed Runtime ignores the proxy settings in configuration files. Instead, proxies must be configured using Runtime Admin or the Managed Runtime API.

To configure proxies for a Managed Runtime environment using our web-based admin tool, follow these steps:

1. Log in to the Runtime Admin.
2. Click your project.
3. Click an environment.
4. Click Environment Settings from the left navigation menu.
5. In the Advanced section, click Edit.
6. Under Proxy Configs, click Add New Proxy.
7. Enter the path, protocol, and host.
8. Repeat for up to 8 proxy configurations.
9. Go back to the start of the Advanced section and click Update.
10. Wait for the bundle to finish redeploying.
11. Verify that the proxy configuration is working as expected.

You can also configure proxies for Managed Runtime environments programmatically using the projects_target_partial_update endpoint. The Managed Runtime API often uses the term “target” instead of “environment,” but both terms refer to the same thing.

Here’s an example request that updates an environment to include a proxy configurations for the api and ocapi paths:

When creating or updating environments, the JSON request body accepts an array of proxy configuration objects from a field called ssr_proxy_configs. Proxy configuration objects include host and path, like in configuration files.

To avoid downtime, the steps for adding or removing proxies in a production environment must be done in a specific order.

To add a proxy to a production environment:

1. Edit the environment settings for the production environment using Runtime Admin or the Managed Runtime API. (Follow the instructions described earlier.)
2. Add the new proxy to the environment settings and save your edits.
3. Update your PWA Kit code to use the new proxy.
4. Push a new bundle of your PWA Kit code to Managed Runtime.
5. Deploy the new bundle.

To remove a proxy from a production environment:

1. Update your PWA Kit code to use the new proxy.
2. Push a new bundle of your PWA Kit code to Managed Runtime.
3. Deploy the new bundle.
4. Edit the environment settings for the production environment using Runtime Admin or the Managed Runtime API. (Follow the instructions described earlier.)
5. Remove the new proxy from the environment settings and save your edits.

In local development, you can override the proxy configurations using environment variables.

Set an environment variable called SSR_PROXY1 to override the first element in the proxyConfigs array, set one called SSR_PROXY2 to override the second element, and so on.

Here's how it works: If the environment variable SSR_PROXY1 is set to https://api-staging.example.com/api, it replaces the first element in the proxyConfigs array with the following proxy configuration object:

These environment variables are commonly used with the npm start command during local development to use different instances of the API host, such as staging or production. Here’s an example that overrides the first proxy configuration object so that the api path routes requests to a staging instance:

After proxy settings have been configured, you can look them up using the utility function getProxyConfigs from the PWA Kit React SDK. For example, you can use a different client ID, depending on the environment that your code is running in:

When a request is proxied, both the request to the origin and the response from the origin are both modified to make them work transparently with your application code.

The following modifications are applied to the request before sending it to the host:

• Remove the /mobify/proxy/<PROXY_PATH>/ prefix.
• Add an HTTP header of X-Mobify: true.

Proxied requests forward all query string parameters and headers, including cookies.

The following modifications are applied to the response before sending it to the client:

• Add an HTTP header of X-Request-Url: <URL> with the URL that was requested.
• If the response is a redirect and the response’s Location header whose host matches the proxy’s host, then host is prefixed with /mobify/proxy/<PROXY_PATH>/.
• If the response contains Set-Cookie headers whose domain matches the host of the proxy, they’re updated to match it. For example, Set-Cookie: key=val; domain=api.commercecloud.com is updated to Set-Cookie: key=val; domain=www.northerntrailoutfitters.com.
• If the response contains an Access-Control-Allow-Origin header whose value matches the proxy’s host, it’s updated to Access-Control-Allow-Origin: https://www.northerntrailoutfitters.com.

To test your modifications, configure a proxy configuration with httpbin.org as the host. When you make a request to through that proxy, it echoes back any headers that it receives.

By default, proxied requests are uncached by the CDN. This default allows proxies requests to be used transparently in your code, without having to worry about incorrectly caching responses.

When you do want a proxied request to be cached by the CDN, change the path prefix used in your request from proxy to caching.

Cached proxy requests differ from standard proxy requests in the following way:

• The Cookie HTTP header is removed.

Cached responses differ from standard responses in the following way:

• Any Set-Cookie HTTP headers are removed.

Cached responses include the following HTTP headers so that when the values of these headers vary, the responses are cached separately:

• Accept
• Accept-Charset
• Accept-Encoding
• Accept-Language
• Authorization
• Range

Responses that include other HTTP headers are not cached separately when their values vary.

Proxies have different constraints than the App Server.

• The execution time for proxy requests is limited to 30 seconds. If a response from the origin doesn’t complete in this time, a HTTP 504 is returned.
• The origin must provide a valid certificate and support using TLS 1.2 or greater otherwise a HTTP 502 is returned. You can check whether your origins TLS support using SSL Labs tool.
• There is no limit to request or response sizes.
• Proxied requests can use the Cookie header. Proxied responses can include the Set-Cookie header.
• The proxied host must be publically addressable. If the proxied host is only accessible from within a private network or blocked like demandware.net hosts, then an HTTP error will be returned.
• The caching proxy only supports HEAD, GET, and OPTIONS methods. POST requests aren't supported.

Now that you understand how and why to use proxies in your commerce app, keep exploring the PWA Kit documentation.