API Connect

Introduction

The API Connect Developer Portal is customizable in many ways to allow an API provider to brand their own developer portal according to their own requirements.  One of the ways to achieve this is create a custom theme which can use logos, colors, fonts, and other resources to change the look and feel of the site.  When creating this theme, it will need to be created and tested on a development site.

To make this job easier the first thing I advise every developer customizing a portal site is to configure the site so that it is easier to debug.  With the Portal Admin CLI this is easy to do and can be scripted so could also be part of a CI/CD pipeline process.  The 2 key things I do when developing a site for demonstration, or indeed, debugging a UI issue are:

• Turn off the JavaScript and CSS aggregation
• Enable twig template debug, if necessary

Turn off CSS and JS aggregation

The portal straight out of the box has JavaScript and CSS aggregated – usually you want this to be the case as minimised CSS or JavaScript file improves download speed of your site. 

For development and debugging purposes, however, it is easier to see the multiple files used.  The drupal-config commands of the Portal Admin CLI enable a user to turn of this aggregation quickly.  

1. Log in to the CLI

apic login --server management_server --realm provider/identity_provider --username provider_username --password provider_password

2. Turn off CSS aggregation

apic --mode portaladmin drupal-config:set --server management_server --catalog catalogid/name --org orgid/name --config_name system.performance --config_key css.preprocess --config_value 0

3. Turn off JavaScript aggregation

apic --mode portaladmin drupal-config:set --server management_server --catalog catalogid/name --org orgid/name --config_name system.performance --config_key js.preprocess --config_value 0

4. Turn off advanced aggregation – if you forget to do this then you will find the above settings will not apply

apic --mode portaladmin drupal-config:set --server management_server --catalog catalogid/name --org orgid/name --config_name advagg.settings --config_key enabled --config_value 0

5. Don’t forget to rebuild the cache

apic --mode portaladmin site:cache-rebuild  --server management_server --catalog catalogid/name --org orgid/name

Now you should see in your browser developer tools that the new settings have been applied and can see which CSS is from which file:

These are the most common settings that I change for debugging the front end of a portal site.  You can configure these via the UI as an administrator (Configuration > Development > Performance), but I find it easier and quicker to use these commands in a script.  The drupal-config commands can be used for getting, setting, creating and deleting Drupal configuration objects on the develop portal site, the above use case is the most common one I use. More information on the commands can be found in the IBM Documentation.

Enable Twig debugging for your site

You might also want to override the layout of some element of the portal, e.g. the product content type template, which would mean applying a modified content type template. More information on this can be found in the IBM Documentation.  

To help you see which template is being used where and see suggestions for overriding a template then enabling the twig debug is a good idea.  This used to involve configuring directly on the site – not always possible for those without access or nervous about changing configuration directly.  The portal admin CLI now has the twig commands to enable, disable and check the state of the twig debugging on your site.

1. Log in to the CLI as shown above
2. Enable the twig debug for your site

apic --mode portaladmin twig:debug-enable --server management_server --org orgid/name --catalog catalogid/name

You shouldn’t need to rebuild your cache as the command has this inbuilt.

Now you should see that your site has the twig template debug shown in the developer tools.

For more information on this can be found in the IBM Documentation. 

Ready to start custom theme development

The above settings should be a good first step to helping you create your first developer portal customizations.  DON’T FORGET – if any of the above is done on a Production site to turn these options back off when finished.  Having these options enabled does have an accompanying performance hit which you don’t want with a production site. This is essentially the reverse of what was shown above:

# login
apic login --server management_server --realm provider/identity_provider --username provider_username --password provider_password
# turn on CSS aggregation
apic --mode portaladmin drupal-config:set --server management_server --catalog catalogid/name --org orgid/name --config_name system.performance --config_key css.preprocess --config_value 1
# turn on JavaScript aggregation
apic --mode portaladmin drupal-config:set --server management_server --catalog catalogid/name --org orgid/name --config_name system.performance --config_key js.preprocess --config_value 1
# turn on advanced aggregation
apic --mode portaladmin drupal-config:set --server management_server --catalog catalogid/name --org orgid/name --config_name advagg.settings --config_key enabled --config_value 1
# disable twig debug
apic --mode portaladmin twig:debug-disable --server management_server --org orgid/name --catalog catalogid/name
# cache rebuild if you need to 
apic --mode portaladmin site:cache-rebuild  --server management_server --catalog catalogid/name --org orgid/name

I hope this helps you to get started with your site development, please let us know any feedback or suggestions.

#APIConnect
#developerportal