Move from Classic APIM to APIM 3.0

If Classic APIM assets exist in your environment and both APIM and the new APIM 3.0 features are enabled, the navigation pane includes links to the Migration Tool and the Classic API Manager, Portal Manager, and Subscription Manager:
API Management 3.0 with legacy APIM pages

Migration Tool wizard

The Migration Tool wizard guides you through three main steps:

  1. Select one or more API versions or Proxies to migrate.
  2. Migrate the associated Policies or disable the Migrate Policies toggle to instead use Policies from APIM 3.0 Policy Catalog after migration.
  3. Select the location for the migrated assets.

When you start migration of one or more assets, the migration process happens in the background and you can continue working. An onscreen notification lets you know that the migration is in process. A migration that fails for some reason doesn't block other migrations. You'll receive an email notification when a subscription is successfully migrated.

What migration does

When you migrate an API Version or Proxy, the Migration Tool creates a new Service version in API Management 3.0 without modifying the originals:

  • API Versions become new Service versions with the same name, description, endpoints, accounts, files, tags, and status.
  • Proxies become new Service versions with the same name. Each Proxy endpoint and each mapping rule becomes a Service endpoint.
  • Path objects that map to endpoints or tasks become HTTP methods.
For published API Versions and Proxies, the new endpoint includes only the HTTP methods defined in the API specification. For unpublished API Versions and Proxies, endpoints include all HTTP methods defined by OAS, but with empty definitions.
Important: To migrate existing path objects correctly, publish the API Version or Proxy before migration.

For Policies, if you choose to migrate them:

  • All API Version Policies become rules in a single Policy associated with the new Service.
  • All Proxy Policies become rules in a single Policy associated with the new Service and all its endpoints.
  • Proxy endpoint Policies become rules in a Policy associated with the corresponding Service endpoint.

For Assets, the Migration Tool copies all assets related to the API Version or Proxy to the new Service version project. All references point to the new Service location.

For APIs or Proxies with active or pending subscriptions, the following are also migrated:

  • Applications
  • Subscriptions: Configured for API key authentication with a time-to-live of 365 days.
  • Subscription requests
Migration limits and tracking:
  • When and while the new Service is published, you can't migrate the source API Version or Proxy again.
  • The Monitor Notification Center Activity tab displays migration events. The event notes the destination project of the migrated resources and the user who migrated them.
Important: Always test and validate the behavior of a migrated Service before publishing it.
After migration:
  • A new Service version exists in the Services Catalog.
  • The original API Version or Proxy is not changed.
  • Until you publish the new Service:
    • Calls to the original URL continue to be handled by the original API Version.
  • After the new Service is published:
    • APIM 3.0 forwards calls from the original URL to the new Service.
    • Existing subscriptions continue to work.
    • You can approve or reject pending subscriptions from the new Service.

Known limitations

  • In API Management 3.0, the Service name must be unique in a project and the URL slug must be unique in an environment. If you try to migrate an API Version or Proxy into a location where that name already exists, the migration process appends an underscore and a number to the name.
  • To protect the integrity of migrated assets, after an API or Proxy version is migrated and published in APIM 3.0 migration is locked. You can't migrate it again unless you unpublish it.
  • If you publish a migrated Service with subscriptions and later delete it, a second migration of the same API Version or Proxy does not migrate the associated subscriptions.
  • APIM Policies created in Classic Manager from the Project menu Manage API Policy option aren't included in migration because they aren't part of the API version:
    API Policy from the Project menu

  • Mapping expressions are migrated as is. You should check to make sure that they make sense in the context of the new Service. For example, an expression that relies on uri.pathsegment[1] might not behave as expected.
  • Due to the difference between Services and legacy Proxies, migration of a Proxy with mapping rules that use expressions requires adjustment of the migrated asset. If you receive a 200 error with a message about conversion failure or a 400 bad request error, check and correct the expressions.
  • You might have to adjust the URL that you use to call an external endpoint migrated from a Proxy. The default behavior of API Management 3.0 is to append the end of the path to the URL. For example, for an upstream path of https://google.com with a path of list list, if a user calls https://google.com/list/apps, the URL is updated to https://google.com/apps. If mapping rules append values to the upstream URL, make sure to modify the upstream URL.
  • Migration of an unpublished API version or Proxy results in the Service version endpoint(s) supporting all HTTP methods, with empty definitions.
  • Migration of a published Proxy with mapping rules doesn't use the specification and results in empty endpoints.