Create a new version

What happens

The creator copies an existing API into a new version, for example PizzaShack 1.0.0 → 2.0.0. In the database, a new version is simply a brand-new API: a new AM_API row with the same name and provider. It gets its own resources and scopes. Optionally, one version is marked as the default version.

Who: API creator (Publisher) · Tables written: AM_API, AM_API_LC_EVENT, AM_API_URL_MAPPING, AM_API_RESOURCE_SCOPE_MAPPING, AM_API_DEFAULT_VERSION, GOV_ARTIFACT / GOV_REQUEST*, REG_* · Tables read: everything belonging to the source version

The flow at a glance

This diagram shows a new version being copied from an existing one.

sequenceDiagram
    actor Creator as API creator
    participant Pub as Publisher
    participant DB as APIM DB
    Creator->>Pub: New version 2.0.0 of PizzaShack
    Pub->>DB: read AM_API 1.0.0 and its children
    Pub->>DB: insert AM_API (new API_ID, new API_UUID)
    Pub->>DB: copy URL mappings and scope mappings
    Pub->>DB: upsert AM_API_DEFAULT_VERSION (if default)
    Pub-->>Creator: Version 2.0.0 created

• The new version always starts in the CREATED state and has no revisions yet.
• Existing subscriptions are not copied, because they belong to the old version's API_ID. There is an optional "copy subscriptions" feature, but it runs only when the new version is published.

Step by step

1. New API row. A new row goes into AM_API. It has the same API_PROVIDER and API_NAME but a new API_VERSION, a new API_ID and API_UUID, and a CONTEXT that includes the new version. VERSION_COMPARABLE holds a sortable form of the version string, so APIM can find the "latest" version.

   API_ID	API_UUID	API_NAME	API_VERSION	CONTEXT	STATUS
   1	b41b…	PizzaShackAPI	1.0.0	/pizzashack/1.0.0	CREATED
   2	b887…	PizzaShackAPI	2.0.0	/pizzashack/2.0.0	CREATED

   A lifecycle event (NULL → CREATED) is logged for the new API_ID in AM_API_LC_EVENT.

2. Children copied. The working copy's resources (AM_API_URL_MAPPING) are recreated under the new API_ID (in the test, IDs 3 and 4), together with their scope mappings (order:write → URL mapping 4) and any operation-policy mappings. The registry artifact (including the endpoint config and OpenAPI definition) is copied too.

   • The scope itself isn't copied. Both versions point at the same AM_SCOPE / IDN_OAUTH2_SCOPE row by name.
   • The new version is registered for governance (GOV_ARTIFACT + GOV_REQUEST), just like a new API. See Governance check.

3. Default version (optional). If the creator ticks Make this the default version, AM_API_DEFAULT_VERSION is updated. It holds one row per API name + provider:

   • DEFAULT_API_VERSION is the version that clients get when they call the context without a version, e.g. /pizzashack/menu.
   • PUBLISHED_DEFAULT_API_VERSION is the default version that is actually published right now.

   API_NAME	API_PROVIDER	DEFAULT_API_VERSION	PUBLISHED_DEFAULT_API_VERSION	ORGANIZATION
   PizzaShackAPI	admin	2.0.0	(null)	carbon.super

   Logical link (no foreign key)

   AM_API_DEFAULT_VERSION links to AM_API by name + provider + version strings, not by id. Renaming or deleting versions relies on APIM's code to keep it consistent.

What gets cleaned up

• Deleting one version deletes only that version's AM_API row and its children (see Create an API).
• The AM_API_DEFAULT_VERSION row is removed or updated by code, not by a cascade.

Try it

This query lists all versions of an API and shows which one is the default.

SELECT a.API_NAME, a.API_VERSION, a.STATUS,
       d.DEFAULT_API_VERSION, d.PUBLISHED_DEFAULT_API_VERSION
FROM AM_API a
LEFT JOIN AM_API_DEFAULT_VERSION d
       ON d.API_NAME = a.API_NAME AND d.API_PROVIDER = a.API_PROVIDER
      AND d.ORGANIZATION = a.ORGANIZATION
WHERE a.API_NAME = 'PizzaShackAPI'
ORDER BY a.VERSION_COMPARABLE;

Different in 3.x

3.x works the same way, but has no ORGANIZATION or VERSION_COMPARABLE columns, and no endpoint tables to copy. See 3.x: Create a new version.

Related domains: API definition · Lifecycle & labels