Azure Developer Portal Migration

Alpar Gür
7 min readNov 7, 2022
Photo by Rod Long on Unsplash

Recently, we got on with the migration of Azure developer portal. The legacy version is deprecated and will retire in October 2023.
Or maybe by the time you’re reading this it has already been removed ¯\_(ツ)_/¯ .

What is Azure?

Azure is the cloud-computing portal of Microsoft. Azure API Management (APIM) is a hybrid, multi-cloud management platform for APIs across all environments. Developer portal is one of the API Management components available and it is an automatically generated, customizable website which basically introduces shipped products with API documentations.

Background Information

Currently, I am part of a team at Vaillant Group where we build API services for our B2B partners enabling them to leverage their heating data. Heating data describes all data generated from heating system(s) such as boiler and heat pump. Making this data available increases efficiency and decreases the maintenance costs through laying the fundamentals for remote diagnostic use cases, allowing integration of heating solutions to smarthome applications, and presenting more insights based on consumption data.

Prior to migration

In our case, we decided to replicate the website hosted in legacy version as it is. Legacy version doesn’t offer git versioning, so it wasn’t really an option to copy paste all files into the new one. One possible way to do this is by using the inline editor and create each web content with styles and customize the layouts according to our existing developer portal website. Developer portal 2.0 has a git integration but unfortunately it’s meant to be only for configuration files.

One way is to use inline editor to create and edit pages. Another alternative would be to use HTML codeblock widget to define the whole page and styles. However, this has a potential to grow an unnecessary complexity and would make it seriously unenjoyable to make any global style changes.
To give you a more concrete example, let’s say you have a website consisting of 30 pages and you want to change the font color and size of your heading element. This would mean to edit every single web page just to do a minor design tweak. Image how long it would take to make more…