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 drastic changes. A hybrid approach would more or less end up with a similarly complexity.
What is this post about?
During our research there wasn’t any worthy source about migration or alternative ways to accomplish it other than the documentation offered by Azure and an official demo video introducing the new developer portal.
In this writing, I will be sharing our approach, experience, how we did it, and what are the things that one should pay attention to during the migration.
If you have already watched the above-mentioned video and still looking for more information you will find some useful tips here before you start with anything ;)
Chosen migration method
Ultimately, we opted for the use of inline editor. Let’s face it, it may not be the most attractive method for someone with a technical knowledge but it gets the job done and it is user-friendly. Hence, it makes it easier for
non-technical people in team to carry on any style or content changes within the website.
Custom domain
One necessary step before migration was to adjust the custom domains to route the new develpor portal to the current URL for the legacy version. So that site visitor notice no difference on their sides. This is something you should also consider if you don’t want to publish the new developer portal with a new domain. This can be done with options available under the custom domains section in APIM. It takes some time for changes to take place though.
The choice of web browser
I tried different web browsers in the beginning. In my case, Google Chrome was the best one so far. Although, everything was working fine with other browsers I was receiving annoying error notifications literately at every click which was taking unnecessary place in the browser window.
Migration
Developer portal 2.0 comes with a built-in template and pages aka “contoso”. We used existing pages as our base since most of the preexisting pages were part of our already existing developer portal.
Navigation bar broken-down
Navigation bar consists of the following items, this section explains each in detail:
- Pages
- Media Library
- Layouts
- Navigation
- Settings
- Styles
- Custom Widgets
- Operations
- Help
Pages: This is where all the pages are listed. Using this tab you can add new pages, edit permalinks, and copy an existing page which comes in very handy when there are pages that are structurally identical and only the content needs to be changed. By clicking a page, you can view and edit it.
Media Library: Storage for media files.
Layouts: This can be the most fundamental one. On developer portal, every page depends on a layout. Page elements such as header and footer can be defined inside a default layout. By doing that, every new page will contain the header and footer elements automatically which saves you time and prevents boring repetitive work.
Multiple layouts can be defined for various pages.
Navigation: The menus and menu items are defined here. You can again define multiple navigation menus and name them as you wish. It might be a good choice to stick to the existing ones and adjust them.
However, while adjusting views for anonymous and authenticated user I couldn’t find a way to make specific elements visible only for authenticated users. So I ended up creating two different navigation menus: one for anonymous and one for the authenticated user. And for hiding or making visible a page element, I copied a page, edited it, and made two versions of it. You get the idea.
Settings: This section is similar to an HTML header section for metadata of the website.
Styles: Styles accommodate all of your page styling. You can think of it as a style.css file for developer portal. You can upload fonts, create custom typography items and adjust existing elements font elements, paragraph, hyperlink style. Custom color catalogue can be created using hexadecimal color codes. It also has a cool gradient color feature (I didn’t use it though).
One thing worth to mention is I find it more convenient to define a new typography item for font elements. This lets you to assign styles more quickly
to a page element while using inline editor rather than only editing style for preexisting font style elements. But these preexisting fonts are used for
auto-generated product list, API list, and documentation. Styles of these
auto-generated contents cannot be changed using inline editor.
So, it’s worth to edit preexisting font style elements for consistency.
Custom Widgets: We didn’t feel the need for any custom widget so there isn’t much I can share on that. According to developer portal, custom widgets can only be developed using TypeScript, React, and Vue.
Operations: By clicking the paper plane, the latest version of developer portal is published (this can also be done via APIM). If you try to visit the developer portal without publishing it yet, you will receive an error message: Developer portal has not been published yet.
Second administrative panel
Second panel offers some neat features too:
- Screen Sizes
- Roles
- Save Changes
- Undo & Redo
Screen Sizes: It lets you to preview the website for devices with different sizes (desktop, smartphone, tablet view).
Roles: Lets you switch between anonymous and authenticated user modes. You can switch to the desired mode and preview it. This can be used to verify your adjustments.
Save Changes: SAVE YOUR CHANGES!
Yes, I strongly encourage you to frequently save your changes, rather it be a bunch of new colors in the styling page or just a new page content. Like I said, there is no versioning but at least you wouldn’t get frustrated by a connection lost or a human error. Because it doesn’t cache your changes.
Undo & Redo: These buttons are self-explanatory but I should stress that for the time being they are kind of buggy. So don’t heavily rely on them.
One other cool feature is that editing mode lets you to navigate between pages just by pressing and holding control | command key (depending on your machine) and click on the page you want to switch.
This one also can be used to check if hyperlinks are working properly.
For inline editor there is not much to say, it is very intuitive. Once you get more familiar with the tools you earn speed very quickly.
For now we can call it a wrap! If you took another approach, feel free to share :)
Until then,
Cheers 👾
