Customize API Manager

Overview

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

  • Organization, user, and application data
  • Password validation
  • API Gateway Manager console for testing

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 data

API Manager organization, user, and application objects support user-defined fields called custom properties . These custom properties are stored with all other object properties in API Manager persistence layer (which defaults to Apache Cassandra). You can set and retrieve these custom properties in the same way as the default out-of-the-box Organization, User, or Application fields. 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.

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 (in this case, Skype ID) 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 code fragment marked in bold in the organizations property:
customPropertiesConfig: {
    organization: {
        // custom properties
        skypeid: {
            label: 'Skype'
        }
    }
}
  1. After updating the file, log into API Manager.
  2. Press Ctrl-F5 to refresh.

The Managing Organizations screen now contains the new 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 code fragment marked in bold to the user property in the app.config file:

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

Add a custom property to applications

Similarly, to add a custom property to applications, insert the following code fragment marked in bold to the application property in the app.config file:

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

In both cases, after updating the file, log into API Manager, and press Ctrl-F5 to refresh.

Specify 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: For text fields (the default)
  • switch: For on/off switch fields
  • select: For drop-down list fields
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 API consumer.

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

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