Developer Notes

Côte d'Opale, France. Photo by ANWB

Managing APIM Developer Portal in multiple environments

Azure API Management (APIM) features a very nice portal that people using your APIs can use to try your APIs. It has a CMS built in that allows you to customize the design and manage the static content in the portal.

This is all really nice but once you have your portal setup in your development environment, how do you get those changes to production?

Open Source

The portal is open source, the code is up on Github and you can modify it and run your own instance if desired. This is generally referred to as Self hosted in the APIM documentation. 

If you don't need heavy customization it's a lot easier to run the version that comes with APIM. This is referred to as a managed portal in the docs.

The APIM portal uses a REST API to manage content and you can use that API to export and import the entire site definition. This makes it possible to migrate your customizations between environments. This works both for self-hosted an managed portals, though you'll need to do some additional work to publish changes to a self-hosted portal.

Moving your portal design between environments

The script to manage the portal content are included in the Github repo and work really well. You will need the following to make this work:

  • Azure CLI
  • NodeJS
  • Access to the source and target subscriptions and you should have at least contributor rights on the APIM resources.
    You'll need resource groups, resource names and subscription ids, so you may want to look these up.

This should work on any system supported by Azure CLI, including Linux, Mac and Windows.

To migrate your portal content from one environment to the next follow these steps:

  • Clone the Github repo or download it as a zip and unpack it
  • Open a terminal and login to Azure CLI, if you're not logged in already
  • cd into the scripts.v3 folder
  • Use your favorite editor to fill in the required settings in migrate.bat or script (depending on your OS)
  • Run the script