Migration Guide to API Gateway 2.0.0 or later

API Gateway version 2.0 introduces important changes that require transforming any proxy that was built for a prior gateway version. The main change is the adoption of the new high performance HTTP Connector , also the properties defined for the proxy are different.

If your proxy was automatically generated by the Anypoint Platform and its code has not been modified since in any way, then the provided migration tool should make this change easy for you. If, on the other hand, you have modified your proxy after downloading it – to include HTTPS credentials or any other alteration – then you must modify your project manually.

For these cases we recommend downloading the proxy from the platform in the latest version of the API Gateway, and then copying the changes you’ve made to it.

To migrate from an older version of the API Gateway, you must first configure your API Gateway 2.0 correctly with all of the proxies in place, and only then shut down the old API Gateway and start up the new one. Both versions can’t run at the same time, due to ports overlapping.

Using the API Gateway 2.0 Migration Tool

If you’re using proxies that have been automatically generated by the Anypoint Platform and haven’t modified them since you downloaded them, you can run this migration tool:

Download the Migration Tool by clicking here.
Go to the API Gateway 2.0 Standalone distribution folder.
Run the following script from the command line:

java -jar <path-to-migration-tool>/api-gateway-migration-tool-2.0.4.jar -DagwSourceFolder=<gateway-1.x-folder> -DagwTargetFolder=<gateway-2.0-folder>

You must provide:

The location in your system and name of the JAR file that executes the migration
- DagwSourceFolder: The parent folder of your API Gateway 1.x Standalone distribution. Below this folder you’ll find the apps and domains folders, where the files to transform are stored.
DagwTargetFolder: The parent folder of your API Gateway 2.0 Standalone distribution. Below this folder you’ll find the transformed apps and domains folders.

The tool migrates all your Applications and Domains in your folders in a single sweep. Any applications or domains that have been modified in any way since downloading from off the Anypoint Platform will be ignored by the tool, these will have to be migrated manually.

Migrating your Proxy or API Gateway App Manually

Starting with API Gateway version 2.0.0, the endpoint model is not supported. You can continue to use HTTP Endpoints and connectors (which is not the recommended practise), but you will not be able to manage any policy associated to it, and you won’t obtain any usage statistics. Moreover, with API Gateway 2.0.0 and later, any inbound endpoints that use API Autodiscovery will cause a parse exception when the application/proxy is deployed to the API Gateway.

If you are using an older auto-generated proxy, it is recommended that you use the Anypoint Platform to automatically generate a new one, and then configure the extra functionality that you need, copying the changes you had performed previously on the older proxy.

If you are using the APIKit plugin, make sure that you are using version 1.7.0 or greater. Earlier versions of the plugin are not supported on API Gateway 2.0.0.

These are the two main changes to take into account:

Non blocking strategy

API Gateway 2.0.0 is optimized for non blocking processing strategy, that gives you a clear performance advantage when the application/proxy is run in a high load system. All proxies built for API Gateway 2.0 have a flag set up to enable this feature. To enable this feature, simply include the following line of code at the beginning of your proxy’s XML, along with other configuration elements, outside any of the flows.

<configuration defaultProcessingStrategy="non-blocking" />

Use of listeners

The new transport that comes with Mule 3.7, which replaces the old inbound endpoint model, is the only supported for policy management and statistics generation. You must replace every instance of the HTTP Inbound Endpoint for the new HTTP Listener Connector, you must also add the corresponding XSD schemas to the app.

To replicate changes done on the old HTTP connector onto the new high performance HTTP Connector, use Migrating to the New HTTP Connector as a reference.