Migrate Classic APIM assets to APIM 3.0

POST https://{controlplane_path}/api/1/rest/public/apim_service/service_migration

This APIM 3.0 endpoint migrates Classic APIM assets (APIs, API Versions, or Proxies) to APIM 3.0 Services.

Use this API to migrate Classic APIM assets to APIM 3.0 Services. The migration handles Snaplex linking, gateway routing, and policy configuration. You can migrate assets across environments or within the same environment, and you can migrate multiple assets in a single request.

The migration always runs asynchronously. The response returns a status_token per asset that you can use with the Get Service migration status API to check migration progress.

  • Service name, slug, and version are optional. They default to the source asset values.
  • The API auto-increments duplicate slugs by appending an underscore and a number (for example, my-service_1, my-service_2).
  • Supported source asset types: API, API Version, and Proxy. The API returns an error for unsupported types.

Prerequisites

Environment admin permissions, or read permission on the source asset.

Example

This example uses Basic authentication. For a JWT example, refer to Authentication.

Minimal request

curl -X 'POST' \
  'https://elastic.snaplogic.com/api/1/rest/public/apim_service/service_migration' \
  -H 'Authorization: Basic {base64_encoded email:password}' \
  -H 'Content-Type: application/json' \
  -d '{
  "org_name": "snaplogic",
  "migrate_assets": [
    {
      "asset_path": "/snaplogic/apim/MyLegacyApi/1.0",
      "service_config": {
        "target_path": "/snaplogic/projects/destination"
      }
    }
  ]
}'

Full request with policy migration

curl -X 'POST' \
  'https://elastic.snaplogic.com/api/1/rest/public/apim_service/service_migration' \
  -H 'Authorization: Basic {base64_encoded email:password}' \
  -H 'Content-Type: application/json' \
  -d '{
  "org_name": "snaplogic",
  "migrate_assets": [
    {
      "asset_path": "/snaplogic/apim/MyLegacyApi/1.0",
      "service_config": {
        "target_path": "/snaplogic/projects/destination",
        "name": "MyService",
        "slug": "my-service",
        "version": "1.0"
      },
      "policy_config": {
        "migrate_policies": true,
        "policy_path": "/snaplogic/projects/destination/policies"
      }
    }
  ]
}'

Query parameters

None.

Request header

Use the application/json content type with basic authentication (email and password) or a JWT. For examples, refer to Authentication.

Request body


{
  "org_name": "...",
  "migrate_assets": [
    {
      "asset_path": "...",
      "service_config": {
        "target_path": "...",
        "name": "...",
        "slug": "...",
        "version": "..."
      },
      "policy_config": {
        "migrate_policies": true,
        "policy_path": "..."
      }
    }
  ]
}
Key Type Description
org_name string Required. The name of the environment (Org) for the migration.
migrate_assets array Required. A list of asset migration configurations. Each entry specifies a source asset and its migration target.

migrate_assets fields

Each object in the migrate_assets array contains:

Key Type Description
asset_path string Required. The path of the Classic APIM asset to migrate. If the path doesn't start with /, the API adds it automatically. The asset must be an API, API Version, or Proxy.
service_config object Required. The Service configuration for the migration target.
policy_config object Optional. Policy migration configuration. If omitted, policies aren't migrated.

service_config fields

The service_config object contains:

Key Type Description
target_path string Required. The destination project path for the migrated Service. The project must exist. If the path doesn't start with /, the API adds it automatically.
name string Optional. The name for the new Service. Default: the source asset name.
slug string Optional. The slug for the new Service. Default: the name with spaces replaced by underscores. The API auto-increments duplicate slugs.
version string Optional. The version name for the migrated Service version. Default: the source version name or 1.0.

policy_config fields

The policy_config object contains:

Key Type Description
migrate_policies boolean Optional. If true, migrate policies from the source asset and apply them to the destination Service. Default: false.
policy_path string Required when migrate_policies is true. The destination path for migrated policies. If the path doesn't start with /, the API adds it automatically.

Response

The migration always runs asynchronously. The API returns a status_token for each asset, keyed by snode ID. Use the token with the Get Service migration status API to check migration progress.


{
  "response_map": {
    "<asset_snode_id>": {
      "status_token": "17ed9720-05b2-4e22-9955-04c4534451ae"
    }
  },
  "http_status_code": 200
}
Key Type Description
<asset_snode_id> object Contains one entry per migrated asset, keyed by the asset snode ID.
status_token string A UUID token for polling migration progress.

Error handling

HTTP status codes Message Resolution
400 Invalid request Verify that you provided all required fields. Check that asset_path points to a supported asset type (API, API Version, or Proxy) and that target_path points to an existing project.
401 Unauthorized Verify your credentials and that you have read permission on the source asset.
404 Not Found Verify the environment name and asset path are correct.