Skip to main content

Deploying an API

API Studio

The Deploy stage of an API shows each environment, the version it serves and the URL to call. Deploying, promoting, rolling back, deprecating and retiring need the API deploy permission.

The Deploy stage​

Each environment shows:

ItemMeaning
VersionThe version deployed there, with its state: Active, Deprecated or Retired.
URLThe base URL of the deployment. Copy puts it on the clipboard.
Flow versionsThe flow version pinned for each flow endpoint.

An environment with nothing deployed says so.

Deploying a version​

  1. Open the API and open the Deploy stage.
  2. Press Deploy.
  3. Choose the Version and the Environment.
  4. For each flow endpoint, choose a flow version, or keep Newest saved version.
  5. Read the changes listed against the version deployed in that environment.
  6. Press Deploy.

Only published versions are listed. A retired version cannot be deployed. The new deployment replaces the one active in that environment.

The change list compares the chosen version with the one already deployed. A breaking change is shown, not blocked.

Promoting a version​

Promotion moves the deployed version and its pinned flow versions to the next environment, in the order Dev, Test, Prod. It needs the API deploy permission.

  1. On the Deploy stage, press Promote to beside the environment that serves the version.
  2. Read the spec changes, the flow version changes and the test gate status.
  3. Press Promote.

Breaking changes are listed first. A breaking change is shown, not blocked. The promoted deployment replaces the one active in the target environment.

Deploying or promoting a version to Test runs its generated contract tests against the new deployment. The run appears under API Studio > Test > Test suites. See Testing an API.

The test gate​

The Test gate section of the Deploy stage shows whether the gate is on for the API. It is on by default.

While it is on, a version reaches Prod only when its latest test run against Test passed. The Promote dialog names that run. With no run, or a failed one, Promote stays disabled.

Owner and Admin can turn the gate off or on. Every change is recorded in the audit log.

Rolling back​

  1. On the Deploy stage, press Roll back beside the environment.
  2. Check the version it restores.
  3. Press Roll back.

A rollback restores the previous deployment in that environment: its version and its pinned flow versions. The replaced deployment stays in the history, so a second rollback undoes the first. Roll back shows only when the environment has a previous deployment.

History​

Each environment lists its earlier deployments under History, newest first. Promotions and rollbacks are recorded in the audit log.

Deprecating a version​

  1. On the Deploy stage, press Deprecate version beside the version.
  2. Optionally set a Sunset date and a Deprecation link to migration notes.
  3. Press Deprecate.

A deprecated version keeps answering and adds deprecation headers. See Policies and limits.

Retiring​

  • Retire version stops the version everywhere. It answers 410 and cannot be deployed again.
  • Retire deployment stops the deployment in one environment only. The environment serves nothing until the next deployment.

Retiring a version is final.

Testing a deployment​

API Studio > Test > Try it lists each environment where the selected version is deployed as a Target, beside Simulated. A deployed target needs an API key from a client in that environment, runs the deployed flow and counts as a live call. See Clients and keys.