Migrate Azure API Management developer portal customizations between instances

A quick overview of how to migrate developer portal customizations between API Management instances

The nice thing about the developer portal of API Management is that you get a good-looking website to access your API documentation out of the box. The default portal usually satisfies after you change some of the default stylings with the built-in visual editor.
When you have multiple instances running (e.g. staging and production) it becomes more of a hassle to change the styling by hand. Luckily for us, the API Management Team has created tooling to help us with that. This also makes it possible to version control your customizations.

Requirements

• Azure CLI
• Node.JS

Getting Started

First, we clone the Management developer portal repository. The repository includes everything you need to self-host the portal but also tooling to facilitate the deployment of hosted portals.

git clone https://github.com/Azure/api-management-developer-portal.git
cd api-management-developer-portal

Install the NPM packages

npm install

The relevant scripts are currently found in the scripts.v3 folder

cd .\scripts.v3\

The folder contains different scripts to download and deploy the developer portal.
Make sure you are logged in with az login command before going further.

Download the customizations

First, we want to download our currently deployed developer portal customizations. We use the following command:

node ./capture ^
--subscriptionId <your-subscription-ID> ^ 
--resourceGroupName <your-resource-group> ^  
--serviceName <your-instance-name>

The script creates a ..\dist\snapshot\ folder that contains two things. A json file that with all the portal customizations and a media folder with all the uploaded images.

Note: When no images are currently uploaded to the portal, a media folder is missing in the snapshot folder. To prevent deployment errors further down, we need to create an empty one.

mkdir -p ../dist/snapshot/media

Deploy the customizations

We need to remove the current customizations on the destination instance. This removes pages, media files and configuration. Deployed API’s will be preserved.

node ./cleanup ^
--subscriptionId <your-subscription-ID> ^ 
--resourceGroupName <your-resource-group> ^  
--serviceName <your-instance-name>

Now we import the customizations from the ..\dist\snapshot\ folder into the destination instance.

node ./generate ^
--subscriptionId <your-subscription-ID> ^ 
--resourceGroupName <your-resource-group> ^  
--serviceName <your-instance-name>

Publish the customizations

When you now go to the built-in editor of the destination portal, you will see the currently imported customizations. These customizations are not visible to end-users because the portal is yet deployed. You can do this through the Azure Portal itself but the last step can also be done programmatically.

At this time the repository does not contain a stand-alone script to deploy the customizations. I have created my own version based on the currently available scripts.

Create a file with the name publish.js in the script.v3 folder with the following content:

const { ImporterExporter } = require("./utils");

const yargs = require('yargs')
    .example(`node ./publish ^ \r
    --subscriptionId "< your subscription ID >" ^ \r
    --resourceGroupName "< your resource group name >" ^ \r
    --serviceName "< your service name >"\n`)
    .option('subscriptionId', {
        type: 'string',
        description: 'Azure subscription ID.',
        demandOption: true
    })
    .option('resourceGroupName', {
        type: 'string',
        description: 'Azure resource group name.',
        demandOption: true
    })
    .option('serviceName', {
        type: 'string',
        description: 'API Management service name.',
        demandOption: true
    })
    .help()
    .argv;

async function publish() {
    const importerExporter = new ImporterExporter(
        yargs.subscriptionId,
        yargs.resourceGroupName,
        yargs.serviceName
    );

    await importerExporter.publish();
}

publish()
    .then(() => {
        console.log("DONE");
        process.exit(0);
    })
    .catch(error => {
        console.error(error.message);
        process.exit(1);
    });


module.exports = {
    publish
}

And run the script as follows:

node ./publish ^
--subscriptionId <your-subscription-ID> ^ 
--resourceGroupName <your-resource-group> ^  
--serviceName <your-instance-name>

Even after the script is finished the publishing process may take a few minutes to complete. After that, you will see that the customizations are visible to end-users.

Share this