Using the Managed Runtime API

The Managed Runtime API allows you to programmatically control apps deployed to Commerce Cloud’s Managed Runtime. It can be used to create custom tooling with the same basic functionality of the Runtime Admin web application, while offering you even more administration abilities and configuration options.

The Managed Runtime API exposes endpoints for controlling the following parts of your app’s runtime.

Projects

Projects represent a specific application and include important settings like project ID. Projects contain targets and bundles.

Targets/Environments

Targets are what run your app’s code. In the Runtime Admin tool, targets are called "environments," but the two different terms refer to the same thing.

Targets can be long lived (like production or staging) or short lived (like sept-load-testing or new-hero-banner).

Target/environment IDs can be up to 19 characters long and must be unique to the project.

Bundles

Bundles contain your app’s code at a specific point in time. Bundles are immutable release artifacts containing JavaScript and other resources to run your app.

Deployments

Deployments describe the act of attaching the code from a bundle to a target.

Before You Begin

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.

Mobify Branding

The company that originally developed Managed Runtime was called Mobify, and it was acquired by Salesforce in 2020. That’s why the base URL for the Managed Runtime API is on the mobify.com domain. The rebranding process is still ongoing.

Tutorial

We’re about to show you how to use the API with a brief tutorial based on some sample requests, which are formatted as curl commands.

Before running the commands, replace any placeholders with actual values. Placeholders are formatted like this: {{placeholder}}.

For most requests, you must replace {{project_id}} with your actual project ID. To look up your project ID, log in to the Runtime Admin tool and go to your project’s settings page.

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

Working with Targets

By default, all projects start with a target called production, but it’s useful to create other targets to use during development and testing.

With our first request, we can get a list of a project’s targets:

Now let’s create a target called staging that we can use to verify changes before deploying them to production:

To use your new target, you must deploy a bundle to it.

Let’s review the details of the staging target we created:

Finally, let’s modify our staging target to set its configured proxies:

Changing the configuration causes the current bundle to be redeployed automatically so that the changes can take effect.

If you’re having trouble with the commands:

  • Try using curl’s --fail argument to display errors.
  • Check your API key.
  • Check your project’s ID.

The API endpoints also work in a browser. Log in to the Runtime Admin tool then open the endpoint you’re using directly in your browser.

Restricting Target Access to Specific IPs

Use these steps only when your security policy requires you to restrict access to environments by IP. Generally speaking, we recommend restricting access using HTTP authorization or a secret HTTP header checked in request processor or the app server.

Now let’s look at another sample request.

Consider the staging target we created earlier, and imagine we wanted to restrict access to specific IPs. You can restrict access to staging using the API by updating the value of ssr_whitelisted_ips.

First, let’s fetch the settings for the staging target:

Now update staging by passing in the set of IPs that are explicitly allowed to access it.

IPs in ssr_whitelisted_ips use the CIDR format and are comma-separated.

Following these steps, you can modify any of the target settings returned by the JSON object returned by the /target endpoint.

Next Steps

Now you’re familiar with what the API can do—and even made some sample requests! To learn more about the API, refer to the API Specification.