Automate Environment Administration with the Managed Runtime API

Use the Managed Runtime API to automate the administration tasks in your app. The API offers similar capabilities like the Runtime Admin, in addition to administration options.

Considerations for Using Managed Runtime API

The Managed Runtime API is for administration purposes only. Do not make requests to the API in your storefront code. Requests that exceed Managed Runtime API Rate Limits are blocked. Because environments created via the CLI don’t use eCDN, this section doesn’t list the B2C CLI. We recommend creating an environment in Business Manager in Administration > Storefronts > {Your Storefront}.

Warning

To read environment variables from the storefront, use process.env.
To read and load redirects use the managed endpoint /mobify/redirects/$path.

Before You Begin

The Mobify brand name still appears in the mobify.com domain in the base URL for the Managed Runtime API. Although new Salesforce domains will eventually take the place of the Mobify domain, support for the Mobify domain will continue.

Note

To make API requests, you must include an API key in the HTTP request Authorization header with the value, Bearer $API_KEY. To find your API key, log in to the Runtime Admin tool and go to the Account Settings page.

Treat your API key like a password because it allows scripts to perform operations on your behalf.

Note

This tutorial uses sample curl requests. Before running the commands, replace any placeholders with actual values. Placeholders are formatted as $PLACEHOLDER. Replace $PROJECT_ID with your actual project ID. To get the project ID, see Find a Project.

Project IDs can be up to 20 characters long and must be unique globally.

List Environments

Call the projects_target_list API endpoint to list the environments (called “targets” in the API) for a project:

1curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/" \
2  --header "Authorization: Bearer $API_KEY"

Create an Environment

Create a staging environment to verify changes before deploying to production.

Environments created via the Managed Runtime API aren’t configured with eCDN.

Important

Call the projects_target_create API endpoint. If you’re also creating a project, call the projects_create API endpoint to create an environment:

1curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/" \
2  --request 'POST' \
3  --header "Authorization: Bearer $API_KEY" \
4  --header 'Content-Type: application/json' \
5  --data '{"name": "staging"}'

Then call the cc_b2c_target_info_update API endpoint to connect a B2C Commerce instance and one or more sites to the environment.

1curl "https://cloud.mobify.com/api/cc/b2c/projects/$PROJECT_ID/b2c-target-info/staging/" \
2  --request 'PUT' \
3  --header "Authorization: Bearer $API_KEY" \
4  --header 'Content-Type: application/json' \
5  --data '{"instance_id": "aaaa_stg", "sites": ["DemoSite1", "DemoSite2"]}'

To use your new environment, deploy a bundle to it.

Call the projects_target_retrieve API endpoint to review the staging environment:

1curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/staging/" \
2  --header "Authorization: Bearer $API_KEY"

Modify Proxy Configuration

Call the projects_target_partial_update API endpoint to modify the proxy configuration for staging:

1curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/staging/" \
2  --request 'PATCH'  \
3  --header "Authorization: Bearer $API_KEY" \
4  --header 'Content-Type: application/json' \
5  --data '{"ssr_proxy_configs": [{"path": "api", "host": "kv7kzm78.api.commercecloud.salesforce.com"}]}'

Changing the configuration redeploys the deployed bundle so that the configuration update takes effect.

Troubleshoot the Managed Runtime API Requests

If you’re having trouble using the API, try these troubleshooting steps.

Add the --fail argument to your curl command.
Check your API key.
Check your project’s ID.

The API endpoints also work in a browser. Log in to the Runtime Admin tool, and then open the endpoint in your browser.

Set Up Automation Users

To support continuous integration and deployment using the Managed Runtime API, create an Account Manager user for automation:

Create a user account in Account Manager using a shared email address such as a Google Group. Store the associated credentials and MFA code in a password manager such as LastPass.
Give the user the Managed Runtime User role.
Assign the user the required permissions in Runtime Admin. The user’s Managed Runtime API key can only access what the user’s permissions allow. Keep it specific to the projects that CI/CD needs to interact with.
Create the API key for the user and save it in your continuous integration system.

To keep the Managed Runtime API key active, update the related Account Manager account password as required by your organization’s Account Manager configuration. If the user is deactivated, reset the password to reactivate the account and re-enable the API key.

Managed Runtime API Rate Limits

The Managed Runtime API has rate limits in place for the number of requests allowed per unit of time. Rate limits are applied on a per-user basis, and help ensure fair access for all users.

If your request exceeds a rate limit, the API returns an HTTP 429 Too Many Requests error, and a Retry-After HTTP header that indicates the number of seconds to wait until you can retry. API rate limits can’t be adjusted.

These tables list the rate limits for different API families.

Some endpoints have cumulative rate limits, which means they aren’t throttled on a per-endpoint basis. Instead, cumulative rate limits throttle the combined number of requests across multiple endpoints. All GET requests have a cumulative rate limit. Similarly, all POST, PATCH, and DELETE requests for endpoints that are not individually called out in the following tables have a cumulative rate limit. These limits are described in Default Rate Limits.

Important

Projects and Environments

Method	Endpoint
POST	`/api/projects/`
PATCH	`/api/projects/*/`
DELETE	`/api/projects/*/`
POST	`/api/projects//builds//`
POST	`/api/projects/*/target/`
PATCH	`/api/projects//target//`
DELETE	`/api/projects//target//`
POST	`/api/projects//target//deploy/`

Cumulative 1 Minute Limit	Cumulative 1 Hour Limit
10	100

Cache Invalidations

Method	Endpoint	5 Minute Limit	1 Hour Limit
POST	`/api/projects//target//invalidation/`	15	100

Default Rate Limits

Method	Endpoint	1 Minute Limit	1 Hour Limit
GET	All endpoints combined.	1000	N/A
POST, PATCH, DELETE	All remaining endpoints combined.	100	N/A

Next Steps

To learn more about the API, see the API Specification.

The Open API schemas for the API are available at:

MRT Admin: https://cloud.mobify.com/api/schema.json
MRT B2C Config: https://cloud.mobify.com/api/cc/b2c/schema.json