Upgrading WSO2 API Manager: What to Expect and How It Works

Why upgrade?

Upgrading your WSO2 product to the latest version is an important step for maintaining a secure, stable, and future-ready platform. There are several reasons why an upgrade may be necessary, including but not limited to the following.

One of the most common reasons is the end of life (EOL) of the current product version. When a version reaches EOL, it no longer receives official support, including security patches, bug fixes, or technical assistance from WSO2. Continuing to run an unsupported version can expose your system to operational and security risks. To determine whether your current version is approaching or has reached EOL, refer to the official WSO2 support matrix documentation.

Note: You can check the EOL status of your WSO2 API Manager by referring to the support matrix documentation.

Another key motivation for upgrading is the ability to take advantage of new features and enhancements introduced in recent releases. Each new WSO2 release typically introduces performance improvements, usability enhancements, new capabilities, and better integration options. By staying on an older version, you may miss out on features that can improve developer productivity, simplify operations, or enable new business use cases.

Additionally, upgrading ensures continued access to critical security patches and bug fixes. Older versions may contain known vulnerabilities or unresolved issues that have already been addressed in newer releases. Running a version without these fixes can increase the risk of security breaches, system instability, or compliance issues. Keeping the product up to date helps ensure a more secure, reliable, and robust deployment.

Upgrading your API manager

The WSO2 API Manager migration process is straightforward and follows a simple, step-by-step approach. By executing each step in sequence, the migration can be completed smoothly with minimal effort:

1. Configuration Migration – Migrate the configurations from the existing WSO2 API Manager version to the new version.
2. Extensions and Customizations Migration – Update and migrate any custom extensions or product customizations to ensure compatibility.
3. Resource and Artifact Migration – Involves migrating various resources and artifacts from the older version of the API Manager to the newer one.
4. Schema Upgrade – To make the schemas compatible with newer versions.

Following these clearly defined steps ensures a simple, predictable, and low-risk migration experience.

Note: If you are migrating from a WSO2 API Manager version earlier than 4.2.0, you must contact WSO2 Support for assistance.

What about existing data?

From version 4.2.0 onward, WSO2 API Manager introduces a zero data migration policy for upgrades within the 4.x release stream. This means that existing runtime and configuration data such as APIs, applications, subscriptions, users, and tokens do not require an explicit data migration step during the upgrade.

Instead, backward compatibility is maintained at the data layer, allowing the product to continue operating on existing data without manual transformations. Any required data-level adjustments are performed automatically at runtime by the product when the relevant components are accessed.

The only mandatory upgrade activity is a database schema update. This may include:

• Adding new tables or columns
• Modifying existing columns
• Introducing or updating constraints and indexes

These schema changes are required to support new features and internal optimizations introduced in newer WSO2 API Manager versions but do not alter or move existing data.

As a result, the upgrade process is significantly simplified, with reduced risk and downtime compared to traditional data migration approaches.

Figure 1: Migration process

Key takeaways

Upgrading to the latest version of WSO2 API Manager is a strategic investment in the stability, security, and future readiness of your API platform. With clearly defined upgrade steps and significant improvements in recent releases, the migration process is both predictable and low risk.

Modern versions of WSO2 API Manager ensure continued product support while delivering performance improvements, new features, and enhanced usability. Staying on a supported version also guarantees timely access to critical security patches and bug fixes, reducing exposure to vulnerabilities and operational issues.

From WSO2 API Manager 4.2.0 onward, upgrades within the 4.x release stream are further simplified through a zero data migration approach. Existing APIs, applications, subscriptions, users, and tokens continue to function without requiring explicit data migration, minimizing downtime and manual effort. The only required upgrade activity is a database schema update, which enables new capabilities without altering existing data.