Customizing WSO2 API Manager 3.x portals

4 min readFeb 13, 2020

Introduction

In this article, I will discuss how to customize the Web portals in the API Manager 3.0.0.

WSO2 API Manager team has recently released the API Manager 3.0.0 product (Will release APIM 3.1.0 soon), Wich is the next generation API Management platform from WSO2. API Manager 3.0.0 contains lots of new features including the revamped Publisher and Devportal(Store) web applications. If you are new to WSO2 or API Manager product this article will help you to understand what is WSO2 API Manager and what’s new in the latest 3.0.0 version.

From 2.x to 3.x

In the API Manager 2.x series, Web applications have been developed using the Jaggery JS framework. It is a serverside web rendering engine developed by WSO2 itself. To customize the JaggeryJS applications, You needed to add customizations inside a pre-defined directory (sub-themes), and when Jaggery server serving the web pages, It gives priority to the overridden pages over the default implementation and renders the page with overridden content.

In contrast to that, new API Manager 3.0.0 web apps are developed as Single Page Application(SPA) using the ReactJS library. If you are new to the SPA concept, Here is the explanation of the SPA in ReactJS documentation

A single-page application is an application that loads a single HTML page and all the necessary assets (such as JavaScript and CSS) required for the application to run. Any interactions with the page or subsequent pages do not require a round trip to the server which means the page is not reloaded.

Following is a good example of variations in between pure Server Side Rendering (SSR) and full Client Side Rendering(CSR)

At the moment, we are using the full CSR method in API Manager 3.0.0 (will be in 3.1.0 as well) for rendering react portals.

Following are the major difference in 2.x and 3.x web portals.

3.x web portals are built using ReactJS as Single Page Applications, and the page rendering happens in client-side (In browser), Wherein 2.x it’s about 90% rendered in server-side and client-side DOM content injections performed using HandlebarsJS
3.x portals have loosely coupled with the API Manager backend using product REST APIs, wherein 2.x , data obtained through various methods (i:e Jaggery APIs, Java HostObjects etc ) and was tightly coupled with the backend implementations
3.x portals use npm for dependency management and wherein 2.x we had lack of client-side dependency management tools

and the list goes on ….

So let's get into the customization details.

Customization techniques

There are mainly 3 ways to customize and extend the WSO2 API Manager 3.x.x React web portals (Publisher & Devportal) those are,

Theming using defaultTheme.json
Overriding React components
Writing your own API Portal using WSO2 React components and Data models

In this article, I will cover the first technique which is the easiest way to change the appearance of API Manager UIs. Will explain the other two methods in separate articles.

So let’s get started . . .

Theme using `defaultTheme.json`

Basic theming through defaultTheme.json file is very easy, All you have to do is update the desired filed in the file

<APIM_ROOT>/repository/deployment/server/jaggeryapps/publisher/site/public/conf/defaultTheme.js

and refresh the browser,

That’s it! You don’t need to execute npm commands. No need to have NodeJS or changes in CSS. All you have to do is changing the JSON file and refreshing.

Now the question is

What are the things that I can modify using defaultTheme.js ?

In short, Everything available in Material-UI theming plus WSO2 custom theme extensions.

Long answer, WSO2 API Manager portals use Material-UI (MUI) components library to build the ReactJS apps, MUI has used JSS for styling the components, As a result, they provide theming capabilities through theme JSON file, It’s basically a JSON schema for styling definitions. You can find MUI theming capabilities from their documentation page.

We have extended the MUI default theme file to support changing WSO2 portals specific elements, Such as portal logo.