Migrate from WSO2 API Manager gateway to Apache APISIX

Effort grows mainly with the number of API definitions, the number of distinct throttling policies and subscription tiers, and the number of custom authenticators, mediation sequences or workflows that have to be rebuilt as APISIX plugins. Ten APIs that share one OAuth setup and two throttling tiers are a very different job from fifty APIs with per-application policies and custom Java authenticators. An illustrative split: a team that inventories every API, groups them by identity and policy pattern, and reuses one plugin set for most of them will move far faster than one that rebuilds each API by hand. Ask for the inventory and a count of custom extensions before accepting any estimate.

A fixed-scope quote is agreed in writing before work starts and lists the scope, deliverables and timeline. For a WSO2 move, expect it to name the API groups in scope, the gateway functions being replaced (routing, OAuth validation, throttling, logging), the plugins or plugin runner code to be written, the environments to be built, the parallel-running window and the rollback steps. It should also state what is excluded, such as the WSO2 Publisher and Developer Portal replacement, which WSO2 Enterprise features are retired and who owns post-cutover support. Ask for each deliverable to be tied to an acceptance check.

The migration depends on access and facts that only your organization holds. Prepare the following:

• A full export or inventory of APIs, their versions, subscriptions, applications, throttling policies and gateway environments
• The list of custom authenticators, mediation sequences, workflows and extensions running in WSO2
• Access to your identity provider for client registrations, scopes and test users, plus the token formats it issues
• Non-production environments that resemble production, with representative traffic and certificates
• Named owners for each API group who can approve cutover windows

Also confirm where logs and metrics go today, since those dashboards and alerts need the same treatment as the routes.

Yes, a capable internal team can do it, provided it has engineers who know APISIX routing and plugins, someone who understands how your WSO2 subscriptions and policies are configured, and time to run both gateways in parallel. The hard parts are usually not the route syntax but the policy translation, OAuth validation behavior and the cutover discipline across many API owners. Many teams bring in a partner for the first API group to set patterns, then continue alone. Compare the internal effort with the written scope and be honest about who would own the work after cutover.

Parallel running should last until each API group has passed its acceptance checks under real traffic and the rollback path has been exercised. The length is not a fixed number. It depends on how much traffic each group carries, how many business cycles it must cover (for example, month-end processing), how many consumer applications need to migrate their credentials or endpoints, and how confident the owners are in the throttling and OAuth behavior. Agree the exit criteria for each group in the written scope rather than a calendar date, and keep the WSO2 gateway available for rollback until those criteria are met.

Confirm early whether APISIX will check tokens by calling your provider's introspection endpoint or by verifying JWT signatures locally. The openid-connect plugin uses introspection by default, while setting public_key or use_jwks verifies signatures locally and skips introspection. Each choice affects latency, provider load and revocation behavior, so decide it with your security team and test rejected, expired and revoked tokens explicitly. Your identity provider's own documentation and your API security review should drive the final configuration.

Usually the policies translate, but the counting model needs attention. The limit-count plugin keeps counters in local memory by default, while sharing them through Redis, Redis Cluster or Redis Sentinel. Routes in the same group share one counter, and rejected requests return 503 by default. Confirm whether your WSO2 tiers count per application, per subscriber or per API, and whether a sliding window is needed (that requires APISIX 3.18.0 or later). Test with production-like load before cutover, because per-node counters behave differently from a single shared counter.

APISIX replaces the gateway runtime only. WSO2 API Manager also includes an API Publisher, a Developer Portal, a control plane and a traffic manager for throttling, and APISIX does not provide those web interfaces out of the box. Before the move, list every lifecycle step your teams perform in the Publisher and every portal feature developers use, such as subscriptions, API keys and documentation. Each item needs a new home: a Git-based catalog, an existing developer portal, a self-hosted portal product, or a small internal tool that calls the APISIX Admin API. Confirm the target for each function with the people who own it, because a gateway migration that leaves subscriptions or key issuance unassigned will stall at cutover. The APISIX documentation is the right starting point for what the gateway itself provides.

Map each WSO2 throttling tier to a rate-limiting plugin on APISIX, most often limit-count, and decide where the counters live. By default, limit-count keeps counters in local memory per gateway node, so limits apply per node unless you share them. Shared counters use redis, redis-cluster or redis-sentinel, and routes that share a group name share one counter. Rejected requests return 503 by default, so change the rejection status if your clients expect 429. Subscription-level and application-level tiers usually become consumer-scoped or route-scoped configurations, and some WSO2 tiers may have no direct equivalent, which you should record as a decision rather than an assumption. Sliding-window limiting requires APISIX 3.18.0 or later. Ask the migration team for a table that lists each WSO2 policy, its APISIX target and the expected behavior during a traffic spike.

Usually yes, if your identity provider issues tokens that APISIX can check. The openid-connect plugin validates tokens through the provider's introspection endpoint by default. You can instead set public_key or use_jwks so that APISIX verifies JWT signatures locally and skips introspection, which removes a network call per request but changes how revocation is detected. Choose the mode by checking how your current WSO2 setup validates tokens, which claims it reads, and how quickly revoked tokens must stop working. Test with real token types, including opaque tokens, JWTs with custom scopes and tokens from each client application. Keep the identity provider unchanged where possible, so the migration tests the gateway rather than the login flow.

The duration depends on the number of APIs, the number of distinct authentication and throttling patterns, and how many consumers must be coordinated. Timing is set in the written scope and depends on your environment, so no duration is given here. The main drivers are the count of WSO2 policies that need translation, the number of consumers that must change base URLs or tokens, whether you run both gateways in parallel with a traffic split, and how much of the lifecycle and portal work moves at the same time. Moving the least critical API group first usually shortens the learning curve for later groups. Ask any partner to break the schedule into inventory, translation, parallel running, cutover and decommissioning, with an owner for each stage.

A capable platform team can do it, provided it has someone who understands both the WSO2 deployment and APISIX configuration, and time to run both gateways in parallel. The work includes exporting WSO2 API definitions, policies and application subscriptions, translating them, testing auth and limits, and building the replacement for the portal functions. Teams often underestimate the test effort for consumers and the design of rollback. A partner is useful when the inventory is large, when policies are heavily customized, or when internal staff are needed for other priorities. Ask for a written list of deliverables so you can compare a self-run plan with a fixed-scope engagement on equal terms.

Keep the WSO2 gateway serving production traffic until each API group is proven on APISIX, and keep its control plane available for the period you need to read configuration and subscription history. Route traffic to APISIX gradually, for example with a DNS or load-balancer split, and keep the WSO2 route as the rollback target. Freeze changes to any API while it is being moved, so both sides do not drift. Record the exact WSO2 release in use. WSO2 API Manager 4.7.0 was released on April 29, 2026, and its repository notes that building it requires JDK 21, which matters if you rebuild custom extensions or authenticators. Decide the decommissioning date only after rollback has been tested and consumers have confirmed their traffic.

Some custom logic will need rewriting, but not all of it needs to be rewritten in the same way. APISIX plugins can be written in Lua, or through plugin runners in Java, Go and Python, and WebAssembly is also supported. First, check whether each custom mediation step is still needed, because many header, rewrite or auth steps map to built-in plugins. Where logic is truly custom, select the implementation language by the skills your team maintains. Test each custom plugin against the same inputs as the WSO2 version, including error responses and edge-case headers. Treat any unmapped custom behavior as a design item with an owner, not a loose end at cutover.

ADC (API Declarative CLI) is an Apache-2.0 tool published by API7 that works with Apache APISIX and API7 Enterprise Admin APIs. It offers ping, dump, diff, sync, lint and convert openapi commands, which can help you compare declared configuration with a running gateway and keep it under version control. Its convert openapi command can help bootstrap definitions from existing OpenAPI documents, but generated output still needs review against your WSO2 policies, because throttling tiers and subscription rules do not translate automatically. Confirm the tool version and its supported APISIX release before you depend on it, and check its repository at the ADC repository for current command behavior.