Skip to main content

Migrating to APIMatic V3

APIMatic V3 is a major release of APIMatic that contains new features, improvements and bug fixes. Since this is a major release, a manual migration is required. This document describes how to migrate your account and your published artifacts (such as your API Portal and generated SDKs) to APIMatic V3.

What's New in APIMatic V3?​

APIMatic V3 contains breaking changes. Please review these changelogs carefully before upgrading:

Migration Timelines​

You are encouraged to upgrade to APIMatic V3 as soon as possible because it contains new features, improvements and fixes that improve the Developer Experience of your users.

To ensure that the migration goes smoothly, we have provided a Migration Window for migrating to APIMatic V3:

  • You can migrate to APIMatic V3 starting now.
  • You can migrate back and forth between APIMatic V2 and V3 during the Migration Window. This Migration Window is provided for you to use APIMatic V3 to test out and publish your updated API Portals and SDKs.
  • The Migration Window ends on November 1, 2021. After this date, APIMatic V2 will no longer be accessible.

Please try to migrate to APIMatic V3 as early as possible so that there is sufficient time for you to test your updated API Portal and generated SDKs.

Migrating Your Account from APIMatic V2 to V3​

Depending on whether your account is part of a team, you can migrate an individual user account or the entire teams' accounts to APIMatic V3. Note that migrating the account by itself does not affect any of the API Portals or SDKs created using APIMatic. They will have to be upgraded separately.

Migrate Individual User Accounts​

This section lists steps to be taken to migrate an individual user account (the account isn’t part of a team).

  1. Login to the desired APIMatic account.

  2. From the APIMatic Dashboard, click on the Switch to V3 button located at the top right.

    Switch to APIMatic V3

  3. From the Welcome modal, click the Upgrade button to confirm you want to upgrade to version 3.

  4. You’re now on APIMatic V3, as is displayed on the Dashboard navigation bar.

    Upgrade to APIMatic V3

Migrate Team Accounts​

Team accounts (user accounts part of a team) are migrated collectively and can only be migrated by the Team Owner. Only the Team Owner would be able to see the Switch to V3 button on the Dashboard. When a Team Owner migrates, all accounts that are part of that team are migrated automatically. The steps that a Team Owner has to take to migrate are the same as listed for individual user accounts except that they must be performed using the Team Owner's account.

Upgrading API Portals to APIMatic V3​

First, ensure that you have migrated your account to APIMatic V3. Migrating the user or team account by itself does not affect any of the API Portals or SDKs published using APIMatic. They will remain published in their last state as it was before the migration.

To migrate the API Portals to APIMatic V3, check out the following options:

Existing Published API Portal​

You can upgrade an existing published API Portal to APIMatic V3 by replacing it. This applies when you do not intend to keep your old API Portal after upgrading it to APIMatic V3.

To upgrade portals that were previously published using APIMatic V2, you need to navigate to the new Portal Editor and re-publish the API Portal on the same publishing slug. Publishing would then update these API Portals to the new APIMatic V3 API Portal.

danger

Note that in case your API Portal is hosted with APIMatic, republishing an existing API Portal using APIMatic V3 will unpublish all previous API Portals for that API, including the API Portals published for the previous versions of the API.

New API Portals​

If a Portal was never published against an API using APIMatic V2, and now the account has been migrated to V3, publishing an API Portal for that API will publish a APIMatic V3 Portal.

Upgrading the SDKs​

If your SDKs were made available as part of your API Portal, please follow the instructions for upgrading your API Portal to APIMatic V3. The API Portals published using APIMatic V3 also contain updated SDKs generated using the new Code Generator for APIMatic V3.

If you do not have an API Portal and just want to generate an SDK, please follow these steps for generating an SDK after migrating your account to APIMatic V3.

Preservation of Data on APIMatic V2​

On migrating your account to APIMatic V3, the Portal Settings for all APIs are locked and preserved. Any changes made to the Portal Settings after migration will not interfere with the preserved data. If the account is downgraded back to APIMatic V2, those preserved settings would be restored to the state that was at the time of upgrading to APIMatic V3.

info

APIs are not preserved. Any changes made to the API via the APIMatic API Editor after migration to V3 will be permanent changes. These changes would hold if the account is downgraded back to V2.

FAQs​

I want to test APIMatic V3 without affecting my published portals. What should I do?​

Note that previewing a portal does not automatically publish it. You can safely preview your portal without needing to publish it. However, if you do need to publish your portal as part of the testing process, you can publish the V3 portal on a slug that is not the same as used for the V2 portal.

In this case, both the V2 and the V3 portals can co-exist, the V2 portal being accessible on the original slug and the V3 portal available on the new slug. This would not affect existing published portals and you can test v3 portals.

I have an API Portal hosted on the APIMatic domain. How do I update it to V3?​

Upgrade your account to V3 and re-publish your portal as described for existing published portals.

I have embedded an API Portal on my own Website. How do I update it to V3?​

Upgrade your account to V3 and re-publish your portal as described for existing published portals. When publishing, choose the Embedded option and re-embed the new script that you get from APIMatic.

I have an APIMatic Portal hosted on my own domain. How do I update it to V3?​

Upgrade your account to V3 and re-publish your portal as described for existing published portals.

I don’t know who the team owner is or I have lost access to our Team Owner account. How do we upgrade to V3 as a team?​

Please get in touch with your Account Executive or raise a support ticket. We’ll get back to you with a resolution.

I published my API Portals using V3, but I want to downgrade them back to V2 temporarily. How can I do that?​

Downgrade your account back to APIMatic V2 and then for:

  • Hosted Portals on APIMatic domain: Re-publish the portals on the same publishing slug
  • Hosted Portals on custom domain: Re-publish the portals on the same publishing slug
  • Embedded Portals: Generate the embed script and re-embed it. The above will restore your Portals to APIMatic V2.

How can I downgrade my account from APIMatic V3 to V2?​

You have the option to downgrade from APIMatic V3 to V2 during the Migration Period.

Individual User Accounts​

This section lists steps to be taken to downgrade individual user accounts, i.e. if the account being migrated isn’t part of a team.

  1. From the the APIMatic Dashboard, click on the Switch back to V2.0 button located at the top right.

    Switch to APIMatic V2

  2. Optional: From the modal that appears, provide a reason for downgrading.

  3. Click the Downgrade button.

    Switch to APIMatic V3

  4. You’re now back on APIMatic V2.

Team Accounts​

Only the Team Owner can downgrade and all team accounts belonging to that team are downgraded collectively. The steps that the Team Owner has to take are the same as listed for individual user accounts.