Skip to content

Publish to the gateway

What happens

When an API is published, the Publisher builds a gateway configuration (a Synapse XML "artifact") and gets it onto the gateways. By default in 3.2, it pushes the artifact straight to each gateway environment. If the gateway artifact synchronizer is turned on, it saves the artifact in the database instead, keyed by gateway label, and the gateways pull it from there.

Who: Publisher → Gateway · Tables written (default): AM_API_LC_EVENT, registry REG_* · Only with the synchronizer on: AM_GW_PUBLISHED_API_DETAILS, AM_GW_API_ARTIFACTS · Tables read: AM_API, AM_API_URL_MAPPING, AM_LABELS

The flow at a glance

This diagram shows the database-backed path, used when the synchronizer is enabled.

sequenceDiagram
    actor Creator as API creator
    participant Pub as Publisher
    participant DB as Database
    participant GW as Gateway
    Creator->>Pub: Publish PizzaShack 1.0.0
    Pub->>DB: upsert AM_GW_PUBLISHED_API_DETAILS
    Pub->>DB: upsert AM_GW_API_ARTIFACTS (label, Publish)
    Pub-->>GW: event: API deployed for label
    GW->>DB: read AM_GW_API_ARTIFACTS for my labels
    GW->>GW: deploy Synapse config
  • With the synchronizer off (the 3.2 default), the two AM_GW_* tables stay empty. The Publisher calls the gateways' admin services directly for every environment that is both defined in deployment.toml ([[apim.gateway.environment]]) and selected on the API.
  • Turning it on needs [apim.sync_runtime_artifacts.publisher] on the Publisher and [apim.sync_runtime_artifacts.gateway] (with gateway_labels) on each gateway.

Step by step

  1. Choose where to deploy. In 3.x, a published API is deployed to:

    • the gateway environments selected on the API, out of those defined in deployment.toml. The environment definitions are not stored in the database in 3.x, and the API's selection lives in its registry artifact. If no environment is selected, the API is published but not deployed anywhere.
    • any gateway labels the API is tagged with. The label definitions live in AM_LABELS (LABEL_ID, NAME, TENANT_DOMAIN), with their access URLs in AM_LABEL_URLS. Which labels an API has is stored in the API's registry artifact, not in a mapping table. Labels were originally designed for the Microgateway.

  2. Record the published API → AM_GW_PUBLISHED_API_DETAILS. One row per API.

    API_ID TENANT_DOMAIN API_PROVIDER API_NAME API_VERSION
    8b2c…-uuid carbon.super admin PizzaShackAPI 1.0.0

    Logical link (no foreign key)

    Here API_ID is the API UUID string (the registry artifact ID), not the integer AM_API.API_ID. To join it to AM_API, use provider, name and version.

  3. Store the artifact per label → AM_GW_API_ARTIFACTS. One row per API per gateway label.

    API_ID GATEWAY_LABEL GATEWAY_INSTRUCTION ARTIFACT TIME_STAMP
    8b2c…-uuid Production and Sandbox Publish (binary blob) 2020-09-01 10:15

    Rows like this appear only when database artifact synchronization is enabled. In the default configuration the table stays empty.

    • The primary key is (GATEWAY_LABEL, API_ID), so re-publishing overwrites the row. There's no history.
    • GATEWAY_INSTRUCTION is Publish (deploy it) or Remove (undeploy it), in that mixed case. APIM's SQL compares against 'Publish'. Undeploying keeps the row but flips the instruction.
    • API_ID is a real FK to AM_GW_PUBLISHED_API_DETAILS.API_ID.
    • ARTIFACT is a serialized bundle: the API's Synapse XML plus any local entries, sequences, endpoints and certificates it needs.

  4. Gateway pulls the artifact. A gateway started with gateway_labels = ["Production and Sandbox"] receives an event through the event hub. It then reads the rows for its labels where the instruction is Publish, and deploys them. A gateway that restarts reloads everything for its labels from this table.

  5. Lifecycle → AM_API_LC_EVENT. Publishing is a lifecycle change (CREATED → PUBLISHED), so an event row is written too. See Change lifecycle state.

What gets cleaned up

  • Unpublishing, blocking or retiring the API sets GATEWAY_INSTRUCTION = 'Remove', or APIM's code removes the rows.
  • Deleting the API removes its AM_GW_API_ARTIFACTS rows, then the AM_GW_PUBLISHED_API_DETAILS row. The FK between them is ON DELETE NO ACTION, so the artifacts must go first.

Try it

This query shows what each gateway label is told to do for each API.

SELECT d.API_PROVIDER, d.API_NAME, d.API_VERSION, d.TENANT_DOMAIN,
       a.GATEWAY_LABEL, a.GATEWAY_INSTRUCTION, a.TIME_STAMP
FROM   AM_GW_PUBLISHED_API_DETAILS d
JOIN   AM_GW_API_ARTIFACTS a ON a.API_ID = d.API_ID
ORDER  BY d.API_NAME, a.GATEWAY_LABEL;

Related domains: Gateway publishing · Lifecycle & labels

Different in 4.x

4.x replaces labels with revisions and gateway environments. You snapshot the API as a revision (AM_REVISION) and deploy it to an environment and VHost (AM_DEPLOYMENT_REVISION_MAPPING). Environments added in the Admin Portal live in the database (AM_GATEWAY_ENVIRONMENT), though the ones in deployment.toml still don't. And AM_GW_API_ARTIFACTS is keyed by REVISION_ID instead of GATEWAY_LABEL. The database-backed sync is also the default. See Deploy a revision (4.x).