The Gateway Migration Utility is a tool whose original purpose was to migrate an entity from one API Gateway to another API Gateway. For example, let's say you have a service named "foo" in your development API Gateway. The Gateway Migration Utility can be used to migrate "foo" from your development API Gateway to your production API Gateway.

Before we get into migrating a service, lets first use the Gateway Migration Utility to get the foo service from the development API Gateway. Let's say the URL to the foo service is https://dev.api.gateway.com/restman/1.0/services/foo. 

GatewayMigrationUtility.sh restman
-trustCertificate
-trustHostname
-host dev.api.gateway.com
-port 8443
-username your_username
-password your_password
-method GET
-path '1.0/services'
-query 'name=foo'

The above command would return XML like this. The actual XML will have many more tags. This is just a short sampling to give you an idea of the XML that is returned by the Gateway Migration Utility.

<l7:Name>foo</l7:Name>
<l7:Id>77f8759353276b5da9bf5f505e5caf31</l7:Id>
<l7:Enabled>true</l7:Enabled>

To illustrate what this command did, the Gateway Migration Utility running on your PC made a restman call to your development API Gateway, found the foo service, and then displayed the XML of the foo service in the command line prompt on your PC. This article has more details on listing services using restman.

One of the fundamental features of the Gateway Migration Utility is to migrate a policy or service from one API Gateway to another. This is usually done using the migrateOut command. In this example, the foo service is migrated out of the development API Gateway into a file named foo.xml.

GatewayMigrationUtility.sh migrateOut
-trustCertificate
-trustHostname
-host dev.api.gateway.com
-port 8443
-username your_username
-password your_password
-defaultAction NewOrExisting or NewOrUpdate
-service 77f8759353276b5da9bf5f505e5caf31
-dest foo.xml

Notice the only difference between the prior illustration and this illustration is the use of the migrateOut call. This article has more details on migrateOut.

In the most basic of scenarios, where no changes need to be made to the service, you can immediately move onto migrating the service into the destination API Gateway. In this example, the foo service is migrated into the production API Gateway.

GatewayMigrationUtility.sh migrateIn
-trustCertificate
-trustHostname
-host prod.api.gateway.com
-port 8443
-username your_username
-password your_password
-bundle foo.xml
-results result.xml

This article has more details on migrateIn.

Often, the service exists in both API Gateways. In this scenario, there are a few things to be aware of. First and foremost, when you migrateOut, the defaultAction can be NewOrExisting, NewOrUpdate, or Ignore. Of these three options, only NewOrUpdate will allow you to migrate the service into the target API Gateway if the service already exists in the target.

If one of these 3 actions does not quite fit into your needs, then you can utilize the manageMappings command. With manageMappings, you have more fine tuned control over the action that will occur when the service is migrated into the target environment. For example, you could use ForceNew to create a new service in the target, or Delete to delete the service in the target.

This article has more details on manageMappings.

Whereas migrateOut and migrateIn are used to migrate a policy or service from one API Gateway to another, restman is used when you need to modify some other type of entity, such as a cluster wide property. In this example, the cluster wide property with ID 1a5b56dfad45645645fd5464df65 is exported into the file named foo.xml.

GatewayMigrationUtility.sh restman
-trustCertificate
-trustHostname
-host dev.api.gateway.com
-port 8443
-username your_username
-password your_password
-method GET
-path '1.0/clusterProperties/1a5b56dfad45645645fd5464df65'
-response foo.xml

Here are other notes I've collected through the years:

• Gateway Migration Utility - Arguments File (argFile)
• Gateway Migration Utility - Encoded Password
• Gateway Migration Utility - Hide Progress
• Gateway Migration Utility - List Certificates (restman)
• Gateway Migration Utility - List Cluster Wide Properties (list or restman)
• Gateway Migration Utility - List only Active or Disabled Policies or Services (restman)
• Gateway Migration Utility - List every version of a Policy or Service (restman)
• Gateway Migration Utility - List Services Dependencies [assertions/fragments] (restman)