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 ..distsnapshot folder that contains two things. A json file that with all the portal customizations and a media folder with all the uploaded images.

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 ..distsnapshot 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 not yet deployed. You can do this by adding the publish argument to the last command.

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

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.