Skip to content

Deploy a revision

What happens

The creator takes a revision, a frozen snapshot of the API, and deploys it to one or more gateway environments. APIM:

  1. copies the API's resources, scopes and policies under a new REVISION_UUID, and builds the ready-to-run gateway artifact straight away,
  2. records which environment the revision should run on,
  3. records each gateway's confirmation once it has deployed the artifact.

Who: API creator (Publisher), then each Gateway · Tables written: AM_REVISION, AM_API_REVISION_METADATA, revision copies in AM_API_URL_MAPPING / AM_API_RESOURCE_SCOPE_MAPPING / …, AM_GW_PUBLISHED_API_DETAILS, AM_GW_API_ARTIFACTS, AM_DEPLOYMENT_REVISION_MAPPING, AM_GW_API_DEPLOYMENTS, AM_GW_REVISION_DEPLOYMENT · Tables read: AM_GATEWAY_ENVIRONMENT, AM_GW_VHOST, AM_GW_INSTANCES

The flow at a glance

This diagram shows a revision going from "snapshot" to "running on a gateway".

sequenceDiagram
    actor Creator as API creator
    participant Pub as Publisher
    participant DB as APIM DB
    participant GW as Gateway
    Creator->>Pub: Create revision 1
    Pub->>DB: insert AM_REVISION + copy child rows
    Pub->>DB: save AM_GW_PUBLISHED_API_DETAILS + AM_GW_API_ARTIFACTS
    Creator->>Pub: Deploy to Default environment
    Pub->>DB: insert AM_DEPLOYMENT_REVISION_MAPPING + AM_GW_API_DEPLOYMENTS
    Pub-->>GW: event "revision deployed"
    GW->>Pub: fetch artifact, then report success
    Pub->>DB: insert AM_GW_REVISION_DEPLOYMENT (SUCCESS)
  • The gateway pulls the artifact through an internal REST API on the control plane rather than reading the database directly.
  • AM_DEPLOYMENT_REVISION_MAPPING means "deployment was requested". AM_GW_REVISION_DEPLOYMENT means "this gateway confirmed it".

Step by step

  1. Create the revision. A new row goes into AM_REVISION.

    • ID is the revision number (1, 2, 3 …) per API, so the primary key is (ID, API_UUID).
    • REVISION_UUID is the global identifier that every copied row points to.
    • AM_API.REVISIONS_CREATED goes up by one (for example, 0 → 1). An API can keep only a limited number of revisions (5 by default).
    ID API_UUID REVISION_UUID DESCRIPTION CREATED_BY
    1 b41b… 4b45… first revision (null)

  2. Snapshot the child rows. The working copy's rows are copied with the new REVISION_UUID filled in. For a simple API that's its URL mappings and scope mappings. Operation-policy mappings, client certificates and GraphQL complexity are copied the same way when they exist.

    • AM_API_REVISION_METADATA stores the API-level tier at snapshot time (API_UUID, REVISION_UUID, API_TIER = 'Unlimited').
    • The registry artifact is also copied, into a revision path.
    URL_MAPPING_ID API_ID HTTP_METHOD URL_PATTERN REVISION_UUID
    1 1 GET /menu (null = working copy)
    5 1 GET /menu 4b45…

    Logical link (no foreign key)

    Most copied tables point at the revision through a plain REVISION_UUID column with no FK. The value 'Current API' (in AM_API_ENDPOINTS, AM_API_PRIMARY_EP_MAPPING and AM_BACKEND) or NULL (in AM_API_URL_MAPPING) means "the working copy, not a revision".

  3. Build the gateway artifact (still at revision creation).

    • AM_GW_PUBLISHED_API_DETAILS gets one row per API. Its API_ID holds the API UUID string, plus TENANT_DOMAIN, API_NAME, API_VERSION and API_TYPE. In the test API_PROVIDER was NULL and API_TYPE was http.
    • AM_GW_API_ARTIFACTS stores the built artifact, a zip file in the ARTIFACT blob, keyed by (REVISION_ID, API_ID), where REVISION_ID is the revision UUID.
    • Updating the API also queues a new governance check (GOV_REQUEST), because the default policy governs API_UPDATE too. See Governance check.
    AM_GW_API_ARTIFACTS.API_ID REVISION_ID ARTIFACT
    b41b… 4b45… (zip blob)

  4. Choose where to deploy. Gateway environments created in the Admin Portal live in AM_GATEWAY_ENVIRONMENT (UUID, NAME, GATEWAY_TYPE, ORGANIZATION). Their hostnames live in AM_GW_VHOST, where GATEWAY_ENV_ID is an FK to AM_GATEWAY_ENVIRONMENT.ID.

    Environments from the config file

    The environments defined in deployment.toml, such as the built-in Default environment, are not stored in AM_GATEWAY_ENVIRONMENT. For those environments, both tables stay empty.

  5. Request the deployment. One row per environment goes into AM_DEPLOYMENT_REVISION_MAPPING.

    • NAME is the environment name and VHOST is the chosen host. For the config-file Default environment it's stored as NULL.
    • REVISION_STATUS is APPROVED, or CREATED while a revision-deployment workflow is pending.
    • DISPLAY_ON_DEVPORTAL controls whether the Dev Portal shows this gateway URL.

    AM_GW_API_DEPLOYMENTS also gets a row saying which environment label each revision targets (API_ID = API UUID, REVISION_ID, LABEL = 'Default', VHOST).

    NAME VHOST REVISION_UUID REVISION_STATUS DISPLAY_ON_DEVPORTAL
    Default (null) 4b45… APPROVED true

    Logical link (no foreign key)

    NAME matches an environment by name, either AM_GATEWAY_ENVIRONMENT.NAME or a deployment.toml environment. There's no FK.

  6. Gateway confirms. Each gateway registers itself in AM_GW_INSTANCES and updates a heartbeat there. After it deploys the artifact, APIM records its per-API state in AM_GW_REVISION_DEPLOYMENT.

    • Only one revision of an API can be deployed to a given environment at a time. Deploying revision 2 replaces revision 1 there.
    GATEWAY_ID API_ID ORGANIZATION STATUS ACTION REVISION_UUID
    1 b41b… carbon.super SUCCESS DEPLOY 4b45…

    AM_DEPLOYED_REVISION stays empty

    The schema also has AM_DEPLOYED_REVISION (NAME, VHOST, REVISION_UUID, DEPLOYED_TIME). In 4.7.0, deployments to the built-in gateway don't write to it. To see which gateways have acknowledged a deployment, use AM_GW_REVISION_DEPLOYMENT.

Federated and third-party gateways

For external gateways such as AWS, Azure or Kong: - AM_API_EXTERNAL_API_MAPPING links the APIM API to its ID on the external gateway. - AM_GATEWAY_TOKEN and the AM_GW_PLATFORM_* tables support gateways that register themselves.

See Revisions & deployment.

What gets cleaned up

  • Undeploying removes the environment's row from AM_DEPLOYMENT_REVISION_MAPPING. The gateways' state in AM_GW_REVISION_DEPLOYMENT is expected to change too, though undeploying wasn't tested.
  • Deleting a revision cascades to AM_DEPLOYMENT_REVISION_MAPPING, AM_DEPLOYED_REVISION and AM_API_REVISION_METADATA. The copied URL mappings and so on are removed by code.
  • Deleting the API cascades to AM_REVISION, and from there to everything above. APIM refuses to delete an API that still has subscriptions, though (see Revoke & delete).
  • Deleting an environment cascades to its VHosts, permissions and gateway tokens.

Try it

This query shows where each revision of an API is requested, and what each gateway reported.

SELECT a.API_NAME, a.API_VERSION, r.ID AS REVISION_NO,
       m.NAME AS ENVIRONMENT, m.REVISION_STATUS,
       g.STATUS AS GATEWAY_STATUS, g.ACTION
FROM AM_API a
JOIN AM_REVISION r ON r.API_UUID = a.API_UUID
JOIN AM_DEPLOYMENT_REVISION_MAPPING m ON m.REVISION_UUID = r.REVISION_UUID
LEFT JOIN AM_GW_REVISION_DEPLOYMENT g
       ON g.REVISION_UUID = r.REVISION_UUID AND g.API_ID = a.API_UUID
WHERE a.API_NAME = 'PizzaShackAPI';

Different in 3.x

3.x has no revisions. Publishing an API pushes it to the gateway environments in deployment.toml, and every change to a published API goes live immediately. The optional database sync writes AM_GW_API_ARTIFACTS keyed by a gateway label, with a Publish or Remove instruction. It's off by default, so those tables are usually empty. See 3.x: Publish to the gateway.

Related domains: Revisions & deployment · API definition