Customize API Manager

This topic outlines how to customize API Manager features such as the following:

  • API Manager generated email
  • Organization, user, application, and API data
  • User registration password validation
  • API Gateway Manager console for testing
Note   Typically, there should be little need to perform custom development to re-code API Manager. Any changes made to API Manager code are not supported by Axway. You should use an unmodified API Manager for internal system administration.

Create a custom API portal

For deeper customization and integration with your website, you should use Axway API Portal to create a heavily branded and customized self-service web portal, which enables API consumers to consume APIs that you have exposed. This portal enables API consumers to register user profiles and applications, manage credentials, browse front-end APIs and documentation, monitor application use of APIs, access blogs and forums, and so on.

API Portal is implemented as a stand-alone CMS-based portal, which you can run using the default Axway branding and functionality, or customize and extend to meet your specific requirements and those of your target API consumers. You can deploy the internet-facing API Portal separately from API Gateway and API Manager, with a dedicated web interface to limit potential security breaches. For more details, see the following API Portal documentation:

Customize API Manager generated email

API Manager automatically generates emails by default to confirm actions such as user registration or client application approval. For example, for user registration, you can customize the contents of the following file:

INSTALL_DIR/apigateway/system/conf/apiportal/email/register-user.template.html

Customize the generated email header

The following example shows the default Axway-branded email header in the register-user-template.html file:

<img src="cid:${email.image.logo}" alt="http://www.axway.com" border="0" id="headerImage campaign-icon" />

The following example shows a rebranded custom email header:

<img src="https:/www.acme-corporation.com/portal/images/header.gif" alt="http://www.acme-corporation.com" border="0" id="headerImage campaign-icon"/>

The following example shows the default Axway-branded email footer in the register-user-template.html file:

<em>Copyright © 2018 Axway, All rights reserved.</em><strong>http://www.axway.com</strong>

The following example shows a rebranded custom email header:

<em>Copyright © 2018 Acme Corporation, All rights reserved.</em><strong>http://www.acme-corporation.com</strong>

The generated email includes a company logo as an attachment. You should replace the following default logo file with your custom company logo file:

INSTALL_DIR/apigateway/system/conf/apiportal/email/images/logo.png
Note   The logo file must be named logo.png and be attached to the email or it will fail to send.

Customize generated email templates

The following email template files include references to www.axway.com, and should be customized to suit your environment:

  • api-app-req-template.html
  • approve-api-app-req-template.html
  • approve-apipublish-template.html
  • approve-app-template.html
  • approve-user-template.html
  • create-app-template.html
  • create-registration-token.html
  • create-user-template.html
  • new-password-template.html
  • pending-approve-user-template.html
  • register-user-template
  • reject-api-app-req-template.html
  • reject-apipublish-template.html
  • reject-app-template.html
  • reject-user-template.html
  • request-apipublish-template.html
  • remove-api-app-access-template.html
  • reset-password-template.html
  • trial-new-password-template.html

Email template variables

The generated email template files include replacement variables (for example, email.image.logo, user.email, and so on). These variables are a read-only set, which means that you cannot add new variables, and changing the name of a variable is not supported. However, you can use these variables as needed if customizing generated emails.

All of the email template files have access to the following common variables:

  • email.from
  • email.bounceAddress
  • email.subject
  • email.image.logo
  • apimanager.name
  • apimanager.hostname
  • apimanager.port
  • apiportal.name
  • apiportal.hostname
  • apiportal.port
  • apiportal.request
  • portal.name
  • portal.hostname
  • portal.port
  • appowner.username
  • appowner.email
  • user.role
  • delegate.usermngmt.setting
  • self.reset

Some additional variables are only used in specific template files, which you can view in each file. For example, the api-app-req-template.html file also contains

  • oadmin.name
  • user.name
  • user.email
  • api.name
  • app.name

Customize API Manager data

API Manager organization, user, application, and API objects support user-defined fields called custom properties. These custom properties are stored with all other object properties in the API Manager persistence layer (defaults to Apache Cassandra). You can set and retrieve these custom properties in the same way as the default out-of-the-box Organizations, Application Developers, Applications, or API screens in API Manager. You can extend the respective user interface screens to enable viewing and editing of these custom properties. For user objects, these custom properties can also be set during user registration.

You can configure custom properties using the following object in your API Manager configuration:

customPropertiesConfig: { 
   user: {
      // custom properties...
   },
   organization: {
      // custom properties...
   },
   application: {
      // custom properties...
   },
   api: {
      // custom properties...
   }
}

The following sections explain the required configuration steps in each case.

Add a custom property to organizations

The following example adds a new field for organizations that enables the user to register the Skype ID for an organization. To add a custom property to organizations, perform the following steps:

  1. Edit the following file:
INSTALL_DIR/apigateway/webapps/apiportal/vordel/apiportal/app/app.config
  1. Insert the following example configuration fragment into the organization property:
customPropertiesConfig: {
    organization: {
        // custom properties
        skypeid: {
            label: 'Skype'
        }
    }
}
  1. After updating the file, log into API Manager.
  2. Press Ctrl-F5 to refresh.

The Organizations screen in API Manager will now contain the new custom property.

Example request using a custom property

Using the skypeid custom property, the following example HTTP request creates an organization with this custom property:

POST /api/portal/v1.0/organizations/ HTTP/1.1
content-type: application/json
Authorization: Basic YXBpYWRtaW5AbG9jYWxob3N0OmNoYW5nZW1l
User-Agent: Jakarta Commons-HttpClient/3.1
Host: localhost:8075
Content-Length: 145
{
    "name" : "MyOrg",
    "description" : "My organization.",
    "phone" : "+353 (1) 6742000",
    "email" : "myorg@axway.com",
    "skypeid" : "MYORG",
    "enabled" : true
}

The following example HTTP request updates an organization with this custom property:

PUT /api/portal/v1.0/organizations/c85cf2e6-cb5e-4f37-afb2-5f0d250e40f2 HTTP/1.1
content-type: application/json
Authorization: Basic YXBpYWRtaW5AbG9jYWxob3N0OmNoYW5nZW1l
User-Agent: Jakarta Commons-HttpClient/3.1
Host: localhost:8075
Content-Length: 238

{
    "id" : "c85cf2e6-cb5e-4f37-afb2-5f0d250e40f2",
    "name" : "MyOrg",
    "description" : "My organization.",
    "phone" : "+353 (1) 6742000",
    "email" : "org2@axway.com",
    "skypeid" : "myorg",
    "enabled" : true,
    "restricted" : false,
    "createdOn" : 1367424410635
}

Add a custom property to users

To add a custom property to users, insert the following example configuration fragment into the user property in the app.config file:

customPropertiesConfig: {
    user: {
       // custom properties
        skypeid: {
            label: 'Skype'
        }
    }
}

The Application Developers screen in API Manager will now contain the new custom property.

Add a custom property to applications

Similarly, to add a custom property to applications, insert the following example configuration fragment into the application property in the app.config file:

customPropertiesConfig: {
    application: {
        // custom properties
        skypeid: {
            label: 'Skype'
        }
    }
}

The Applications screen in API Manager will now contain the new custom property.

Add a custom property to APIs

To add custom properties for APIs, insert the following example configuration fragment into the api property in the app.config file:

customPropertiesConfig: {
    api: {
        // custom properties
        customProperty1: {
           label: 'Custom Property #1',
           permissions: {
              admin: { read: true, write: true },
              oadmin: { read: true, write: true },
              user: { read: true, write: false }
            }
         },
         customProperty2: {
            label: 'Custom Property #2',
            type: 'select', 
            permissions: {
               admin: { read: true, write: true },
               oadmin: { read: true, write: true },
               user: { read: true, write: false }
            },
            options: [
               { value: '1', label: 'Value 1' },
               { value: '2', label: 'Value 2' },
               { value: '3', label: 'Value 3' }
             ]
          },
         customProperty3: {
            label: 'Custom Property #3',
            type: 'switch', 
            permissions: {
               admin: { read: true, write: true },
               oadmin: { read: true, write: true },
               user: { read: true, write: false }
          },
          options: [
              { value: true, label: 'ON' },
              { value: false, label: 'OFF' }
           ]
       }
    }
}

The API tab for a front-end API in API Manager will now contain these new custom properties. For example:

Configure custom properties for APIs

Tip   In all cases, after updating your app.config file, log into API Manager, and press Ctrl-F5 to refresh the API Manager screen.

Export and import of custom properties in API collections

When exporting an API collection from API Manager, and custom properties are configured, these custom properties are present in the API collection export file.

When importing an API collection containing custom properties, the custom properties are persisted to Apache Cassandra using the API Manager KPS, and are returned in REST API calls for the front-end API. If the custom properties have also been configured in app.config, they are displayed when editing the front-end API. However, if the custom properties have not been configured in app.config, they are not displayed when editing the front-end API (despite the values being returned in REST API calls), and remain so until app.config is updated, and API Manager is refreshed.

For more details on exporting and importing API collections, see Manage front-end REST API lifecycle.

Custom property message attributes

When configured, custom properties are available to API Manager request, routing, and response policies using the following message attribute:

${api.custom.properties}

This attribute stores the custom properties as name-value pairs as java.util.HashMap<String,String>. You can access the value of a custom property named customProp1 using the following selector:

${api.custom.properties.customProp1}

For more details, see Retrieve custom properties.

For more details on configuring API Manager request, routing, and response policies, see Configure API Manager settings in Policy Studio.

Custom property options

Custom properties are customPropertiesConfig fragments with a unique name (for example, skypeid). You can specify the following options:

Property Option Description
label Required. Friendly name for the property displayed in API Manager (for example, label:'My Custom Property').
type Optional. Can be one of the following:
  • custom: Text field (default)
  • switch: On/off switch field
  • select: Drop-down list field
For example, use type:select to specify a custom property as a drop-down list.
disabled Optional. Can be false or true. Overrides the permissions option. Defaults to disabled:false.
permissions Optional. Read/write permissions per-user role. By default, the property is read and write for all roles. The following shows an example:
permissions:{
     admin:{ read:true, write:true },
     oadmin:{ read:true, write:true },
     user:{ read:true, write:true }
},
options Optional. But required for the switch and select options. The following shows an example:
options:[
    {value:true, label:'One'},
    {value:'ii', label:'Two'},
    {value:3, label:'Three'}
],

Retrieve custom properties

You can retrieve API Manager custom properties at runtime using API Gateway filters and KPS selectors.

Retrieve custom properties for organizations

You can use the Read Organization filter to retrieve custom properties for organizations. This filter automatically populates custom attributes and makes them available to your policy. In this filter, the Organization selector represents the primary key, and enables the organization details to be retrieved from the Cassandra database using the KPS:

${apimgmt.organization.id}

After a successful read, the custom property is available in the resulting attribute, which is configured using Name of attribute to set. For example, with an Organization Selector of ${apimgmt.organization.id}, and a Name of attribute to set attribute set to ${myOrg}, you can access customProperty1 using the following value:

${myOrg.customProperty1}

For more details, see Read organization.

Retrieve custom properties for applications

You can use the Read Application filter to retrieve custom properties for applications. This automatically populates custom attributes and makes them available to the policy. In this filter, the Application ID selector represents the primary key, which enables the application details to be retrieved from the Cassandra database using the KPS:

${apimgmt.application.id}

After a successful read, the custom property is available in the resulting attribute, which is configured using Name of attribute to set. For example, with an Application ID Selector of ${apimgmt.application.id}, and a Name of attribute to set attribute set to ${myApp}, you can access customProperty1 using the following value:

${myApp.customProperty1}

For more details, see Read application.

Retrieve custom properties for users

You can use the Read Application Developer filter to retrieve custom properties for API consumer users. This automatically populates custom attributes and makes them available to the policy. In this filter, the Application Developer ID selector represents the primary key, which enables the user details to be retrieved from the Cassandra database using the KPS:

${apimgmt.appdeveloper.id}

After a successful read, the custom property is available in the resulting attribute, which is configured using Name of attribute to set. For example, with an Application Developer ID Selector of ${apimgmt.appdeveloper.id}, and a Name of attribute to set attribute set to ${myUser}, you can access customProperty1 using the following value:

${myUser.customProperty1}

For more details, see Read application developer.

Retrieve custom properties for APIs

You can retrieve custom properties for APIs by directly querying the KPS using selectors. For example, if a custom property named skypeId is configured, you can retrieve this using:

${kps.PortalVirtualizedAPI["2a461cba-f060-4829-ba43-9d8200369e62"].customProperties.skypeId}

In this case, 2a461cba-f060-4829-ba43-9d8200369e62 is the ID of the virtualized API.

The following example uses a message attribute for the ID:

${kps.PortalVirtualizedAPI[alert.apiIdList].customProperties.internalId}
Note   Custom properties cannot be encrypted. This means that any sensitive data stored in custom properties will be sent in the clear.

For more details on KPS, see the API Gateway Key Property Store User Guide.

Customize API Manager password validation

API Manager enables you to perform custom password validation based on a specified regular expression. For example, you can test for a mix of lowercase, uppercase, and special characters for the API Manager user registration and change password features. If the password characters validate, this returns true. Otherwise, this returns a specified error message, or false.

Validate password for user registration and change password features

You can customize password validation for the API Manager user registration and change password features by editing the following files:

  • User registration:
INSTALL_DIR/apigateway/webapps/apiportal/vordel/apiportal/app-login/app.config
  • Change password:
INSTALL_DIR/apigateway/webapps/apiportal/vordel/apiportal/app/app.config

Configuration steps

In each of these app.config files, perform the following steps:

  1. Specify a custom regular expression in the validatePassword method. For example:
validatePassword:function(password) {
    return /(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{6,}/.test(password);
},
  1. Specify a custom validation message for invalid passwords in the next section. For example:
invalidPasswordMessage:'Password must include uppercase, lowercase, and special characters.',
  1. After updating these files, enter the API Manager URL, for example:
https://localhost:8075
  1. Press Ctrl-F5 to refresh, and log into API Manager.

Customize API Gateway Manager URL for testing

API Manager enables you to specify the location of the API Gateway Manager web console that is used for testing. For example, this enables the Try method button to link to the specified API Gateway Manager console for viewing the transaction log. For more details, see Virtualize REST APIs in API Manager. For more details on using API Gateway Manager, see the API Gateway Administrator Guide.

To specify the location of the API Gateway Manager console, perform the following steps:

  1. Edit the following file:
INSTALL_DIR/apigateway/webapps/apiportal/vordel/apiportal/app/app.config
  1. Enter the location of the API Gateway Manager console. For example:
nodemanager:'https://localhost:8090',
  1. After updating the file, log into API Manager.
  2. Press Ctrl-F5 to refresh.

Further information

Web application developers can use the API Manager REST API to perform custom development. For example, you can use this REST API to view and update the configured users, organizations, applications, and to monitor events related to API Portal and API Manager. For more details, see the API Manager REST APIs.

Related Links