Administration

Tenant Management

Software AG provisions API Cloud in Software AG Cloud platform based on your geographical location. Software AG Cloud has its own Tenant Management System to authenticate users. Once a user registers with API Cloud, the corresponding Tenant Management System initiates the user registration process.

Supported Plans

When you sign up for a webMethods.io API Gateway trial tenant, the Free forever edition is assigned by default. You can then optionally upgrade to the paid plans like Basic, Advanced, or Enterprise based on your requirement. For more details, see the Pricing tab of webMethods.io API in SoftwareAG Cloud site.

Allowed IP Addresses

Overview

webMethods.io API Gateway connects with most third-party services easily and instantly. However, in some cases, you may have to connect to your servers from specific IP addresses, and access resources that lie behind a protective firewall. This can be achieved in webMethods.io API Gateway. SoftwareAG provides a set of static IP addresses that you have to to allow in your firewall. This allows webMethods.io API Gateway to make connections to your servers and run the required services successfully.

Software AG Cloud products are available in several geographical regions, operated by different infrastructure providers. Go to the Software AG Cloud Regions website for information on the available products and also the underlying infrastructure provider in each region.

Currently, webMethods.io API Gateway is available on Amazon Web Services (AWS) and Microsoft Azure. Based on the vendor and the associated region selected by you at the time of creating your tenant, you need to allow relevant IPs to establish the connectivity. Once you add the allowed IP addresses available on the Software AG Cloud page, you should be able to connect to your resources from webMethods.io API Gateway services. If not, contact Software AG Global Support with the required details.

Tenant URL and Software AG Cloud Region

The following table helps you to identify the cloud region based on a your tenant URL. Once you identify your cloud region, go to the Software AG Cloud page for information on the allowed IP addresses.

User Management

User Management in Software AG Cloud

You can manage users and teams information from the Administration page in Software AG Cloud.

Users: User personas who can access API Gateway and perform tasks. There are three user personas, Cloud-Tenant-Administrator, APIGateway-User, and APIPortal-User depending on the roles assigned to the users. Based on the roles, user can access the API Gateway and Developer Portal products.

Teams: Users who share a common role or responsibility can be grouped as teams. When the Team feature is enabled, the members of teams can access the API Gateway assets of their teams and they can perform actions on these assets based on the functional privileges assigned to their teams.

View User Details

You can view user details along with user groups.

To view user details

1. Expand the menu options icon , in the title bar, and select User management.

2. Select Users.
   A list of users appears.

   Note

   The newly created users who have not logged into API Gateway do not appear in the list. But, if the API Gateway Administrator associates those newly created users to user groups in the Group tab, then those users are listed in the user list though they have not logged into Software AG Cloud.

3. Click Login ID of the user that you want to view.
   The User details tab appears with basic information of the user along with user group details appears.

User Groups

API Gateway is shipped with the following predefined groups:

• Administrators

• API-Gateway-Administrators

• API-Gateway-Providers

By default, API Gateway’s Administrator user, is part of Administrators and API-Gateway-Administrators group.

The table lists the privileges based on the user group.

Authentication and Authorization

API Gateway is primarily accessed using API Gateway user interface, which supports Basic authentication and SAML SSO.

You can also use REST APIs to manage API Gateway. To invoke the APIs, you must have the required functional privileges.

Adding a Group

You can add a user to a group. The group is associated to an access profile that contains functional privileges.

To add a group

1. Expand the menu options icon , in the title bar, and select User management.

2. Select Groups.

3. Click Add group.
   The Group details tab appears.

4. Provide the following information in the Basic information section:

   Field	Description
   Name	Name of the user group.
   Description	A description for the user group.

5. Click Save to save the group details at this stage and provide the group information for the user at a later time.

6. Click Continue to associate Users >.
   Alternatively, you can click Users to go to the Users section.

7. Provide the user’s login ID in the Login ID field.
   You can search users based on the characters provided in user name and email id. Select the required user from the list displayed.

8. Click Save.

Modifying a Group

You can modify details for a selected group. You can add users to a group or remove them if required.

To modify a group

1. Expand the menu options icon , in the title bar, and select User management.

2. Click Groups.
   A list of groups appears.

3. Select the group to be modified.
   The Group details tab appears.

4. Click Edit.
   This opens the details of the selected group.

5. Modify the basic information of the user.

6. Modify the user details of the group.
   Edit or delete (by clicking the delete icon) the name of the existing user that appears.

7. Click Save.

Deleting a Group

You can delete a group from the list that appears in the Groups section of the User Management page. Once a group is deleted, the user associated to the group is unable to perform the tasks associated with that group. Deleting a group does not delete the users associated with the group.

To delete a group

1. Expand the menu options icon , in the title bar, and select User management.

2. Click Groups.
   A list of groups appears.

3. Click the Delete icon for the group that has to be deleted.

   Note

   You cannot delete predefined groups.

4. Click Yes in the confirmation dialog.

API Gateway Functional Privileges

The following table lists the functional privileges and their description:

Functional Privilege	Description
Select all	To select all the listed functional controls.
Manage APIs	To create and manage APIs.
Activate/ Deactivate APIs	To activate, deactivate and manage APIs.
Manage applications	To create and manage applications and register applications with the APIs. You cannot modify or delete an application if you are not the owner of the application.
Manage aliases	To create and manage aliases.
Manage global policies	To apply a global policy to all APIs or the selected set of APIs.
Activate/Deactivate global policies	To activate, deactivate, and manage global policies.
Manage policy templates	To apply one or more policy templates to an API.
Manage threat protection configurations	To prevent malicious attacks on applications that typically involve large, recursive payloads, and SQL injections.
Publish API to service registry	To publish and unpublish APIs to service registry.
Manage packages and plans	To create packages and plans, associate a plan with a package, and associate APIs with a package. In addition, you can view the list of packages, package details, APIs, and plans associated with the package.
Activate/ Deactivate packages	To activate, deactivate, and manage packages.
Publish to Developer Portal	To publish and unpublish assets to API Gateway.
View administration configurations	To view administration configurations.
Manage general administration configurations	To create and manage administration configurations.
Manage security configurations	To create and manage security configurations.
Execute service result cache APIs	To execute service result cache API.
Manage destination configurations	To publish events and performance metrics data to the configured destinations.
Manage system settings	To create and manage system settings.
Manage user administration	To create and manage users.
Manage promotions	To create stages and manage promotions.
Manage service registries	To create and manage service registries
Change ownership/ teams	To change ownership of an asset or teams.
Manage scope mapping	To manage OAuth and OpenID scopes.
Import assets	To import already exported APIs, application, policies, aliases, or other assets and configurations using the Import option in the user menu .
Export assets	To export assets to your local system.
Manage purge and restore runtime event	To purge and restore events from the API Gateway store by setting the required date or duration in the API Gateway.
Manage microgateways	To manage the Microgateways connected to the API Gateway instance.
Manage Custom dashboards	To manage custom dashboards in Global Analytics. You can not manage custom dashboards if you do not have this privilege.

Team Support

When users from multiple business units of an organization share the same API Gateway instance, by default, all users have access to all assets irrespective of their departments.

In a typical deployment scenario, all users have same level of access privileges to all API Gateway assets. However, there could be requirement for users from different business units to have different levels of access to specific assets; and they would not want interference from each other.

As a platform administrator, keeping in mind the various role-based access requirements, how do I

• group users of a business unit or a project with similar roles and assign certain assets to these teams

• assign different access privilege to different set of users to specific assets?

This is where the Team support feature of API Gateway is useful. In a shared environment, this feature enables you to provide different level of access to different users to access specific assets.

The Team support is disabled by default; and you must enable the feature to use it. For information about enabling the feature, see Enabling Team Support.

When to use Team support?

Team support can be used to group the users of a business unit or users with similar roles in your organization. Using this feature, you can assign assets for each team and specify the access level of team members based on the team members’ project requirements.

This feature is helpful for organizations that have multiple business units, who work on different projects. Users can access only the assets that are assigned to them. For example, consider an organization with different teams such as Development, Configuration Management, Product Analytics, and Quality Assurance. Each of these teams needs access to different assets at different levels. That is, developers would require APIs to develop applications and they require the necessary privileges to manage APIs and applications. Similarly, analysts would want the necessary privileges to view performance dashboards of assets. In such scenarios, you can group users based on their roles as a team and assign them the necessary privileges based on their responsibility.

Prior to the 10.5 version, users were given the necessary privileges using Access Profiles. Starting version 10.5, you can limit the access of your asset to the required team members and assign access privileges using the Team support feature.

What is a Team in API Gateway?

A team can be defined as a group of users with a set of defined responsibilities.

The assets supported by this feature are APIs, applications, packages, and plans.

This table lists the important points on API Gateway behavior with and without the Team support feature:

Users can manage assets based on the functional privileges assigned to the teams they belong to. For details on asset visibility and accessibility, see Team Support Considerations.

When not to use Team support?

You do not use the Team support feature when you require:

• Tenant isolation. If your requirement is to allow the access of assets by tenants, then you must have multiple tenants and isolate them from each other. The Team support feature does not address this requirement.

• Full access management. Users gain access based on their team privileges. There is no role-based access for users to an asset.

Teams management using API Gateway

You can create teams from the User Management section of the API Gateway UI by including the required user groups and assigning them the required functional privileges. You can also assign a Team administrator for each team, who can add or modify team members.

Users with the Manage user administration privilege can create teams. When creating a team, you can assign:

• Team administrator. You can assign a user or a user group as team administrator. Team administrators can add or remove users from a team. When you assign a user group as team administrator, all users of the groups can modify team members. When team administrators, who do not have the Manage user administration functional privilege log on to API Gateway, they can view only the teams assigned to them in the Teams tab of the Administration page.

• Functional privileges for the team members. The functional privileges assigned to a team determines the accessibility of assets to the respective team members. For example, if you assign all privileges under the APIs, Policies, and Applications sections, then the team members can manage APIs and applications assigned to their teams and perform operations related to policies.

• Team members. You can assign users and user groups to the team. Team members can access the assets assigned to their teams and perform operations on the assets based on the functional privileges assigned to the team.

Teams - Asset Association

After you have created teams, you can assign assets to teams in one of the following ways:

• Assign team during asset creation. When you create an asset, API Gateway provides an option to select the teams for the asset. You can select more than one team for an asset. You can modify the teams assigned by following the Change ownership process. For information about the process, see How do I Modify Teams Assigned to an API? and How do I Change the Ownership of Multiple Teams?

• Using Global Team Assignment rule. This is a preferred method to assign teams when you already have assets to which you want to assign teams to. You can create global assignment rules that are applied to assets and assign teams to them. You can specify one or more conditions in a rule. When an asset satisfies the conditions specified in a rule, the asset is assigned to the teams specified in the rule. When you create and activate a rule, the rule is applied to the existing assets and teams are assigned accordingly.

If you already have assets in your API Gateway instance and when you enable the Teams support feature, all assets are assigned to the Default team. Every user is automatically assigned to this team. That means, by default, every asset (APIs, applications, packages and plans) are still visible to all users. Access rights are restricted only if the asset is explicitly assigned to one or more teams during its creation.

You must manually remove the Default team from the respective asset details page.

Software AG recommends that you read the Team support considerations section to see the impact of Team support on other features. For more information, see Team Support Considerations.

Enabling Team Support

When you enable the Team support feature, you can manage teams from the Teams tab under the User management section of API Gateway.

If you do not enable this feature, you can still create teams, as explained in Creating Teams, and assign functional privileges to users. However, you cannot assign required assets to a set of users and restrict the access of assets to other users.

If you have enabled this feature, created teams, and assigned assets to teams, and then disable this feature, then the team assignments that you had performed earlier become invalid. That is, the assets are available to users based on their functional privileges and not based on the assigned teams.

To enable teams

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > Extended settings.

3. Click Show and hide keys.

   All configurable parameters appear.

4. Select the enableTeamWork from the parameter list.

   The enableTeamWork field appears in the Extended Settingssection.

5. Type true in the enableTeamWork field.

   By default, the value of the setting is set as false.

The feature is enabled.

Creating Teams

This use case explains how to create teams by assigning the required functional privileges and users to them.

This use case begins when you have identified the list of users who must be given access to an asset or a particular set of assets and end when you have created a team including the identified users.

In this example, a team with developers called DevTeam is created with the Dev user group as the team members, User1 as the Team administrator, and all privileges under Manage API, Policies and Applications are assigned to the team. The user, User1, is also allowed to approve the pending requests of the applications that the team owns.

Before you begin

Ensure that you have:

• API Gateway Manage user administration privilege.

• The user group, Dev is created. For information on how to create a user group, see Adding a Group.

To create teams

1. Expand the menu options icon , in the title bar, and select User management.

2. Click Teams.

3. Click Add Team.
   The Create Team page appears.

4. Provide the name and description of the team in respective fields.

5. In the Team Administrators section, provide any or both of the following:

   • Login ID of the user who want to assign as a team administrator in the Login ID field.

   • Name of the API Gateway user group or the LDAP group that you want to assign as team administrator in the Group name field.

   You can search users or user groups based on the characters provided in the above fields. Select the required user from the list displayed.

   For the example consider in this use case, the team is named as DevTeam and the User1 is specified as the team administrator.
   
   

6. In the Approvers section, provide any or both of the following:

   • Users. Users who can view the pending requests of assets that the team is associated with. You can specify login Id of the required users.
   • Group name. User groups that can view pending requests of assets that the team is associated with. The users from the specified groups can approve the pending requests of applications that the team owns and approve them. You can specify names of the required API Gateway user groups or the LDAP groups.
     You can search users or user groups based on the characters provided in the above fields. Select the required user from the list displayed.
   For the example considered in this use case, the User1 is specified as the approver.

7. Select the Include team administrators as approvers option.
   If selected, the users and user groups specified in the Team Administrators section can view the pending requests of the applications that the team is associated with and approve them.

8. Click Continue to assign functional privileges >.
   The Functional privileges list appears.

9. Select the functional privileges to be assigned to the team members. For information on the available functional privileges, see API Gateway Functional Privileges.
   
   In this use case, you need to assign all privileges required to manage the APIs and applications assigned to the team. So, all functional privileges under the APIs, Policies, and Applications section are selected.
   
   

10. Click Continue to assign groups >.
    The Find groups section appears.

11. In the Name field, provide the name of the user group that you want to add as team members.
    For this use case, the Dev user group that has all developers.
    
    

12. Click Save.
    The DevTeam is created and appears in the list of teams.
    
    
    
    You can now assign assets to the team.

How do I Assign Teams during Asset Creation?

This use case explains how to assign teams for an API Gateway asset.

The use case starts when you have an asset that you want to allow access only to a set of users in your organization and ends when you have assigned team(s) to an asset.

In this example, let us see the steps to assign the asset, DevAPI that is being created to a team that has all developers as team members.

Before you begin

Ensure that you have:

• API Gateway Manage user administration privilege.

• The team support feature enabled. For information on enabling the feature, see Enabling Teams Support.

• The team, DevTeam is created. For information on creating team, see Creating Teams.

To assign teams during asset creation

1. Click APIs in the title navigation bar.
   The Manage APIs page appears.

2. Click Create API. The Create API page appears.

3. Click Import from an File.

4. Click Browse to select the file using which you want to create the API.

5. Provide DevAPI in the Name field.

6. From the Team drop-down list, select the teams that you want to assign the asset to. For this use case, select the DevTeam.
   
   
   
   The assigned teams appear in the Team field of Basic Information section in the API details page. In this example, the DevAPI is assigned to DevTeam.
   
   

By default, all assets are assigned to the Administrators team in addition to the teams that you have assigned during asset creation.

How do I Assign Teams Using Team Assignment Rule?

This use case explains how to assign teams to API Gateway assets using Team assignment rules.

Team assignment rules are used to assign teams to existing assets and the ones you create. You can create rule by specifying a set of required conditions. Assets are validated against the given conditions and assigned to the configured teams. If you do not provide any conditions when for a rule, the rule is assigned to all assets in API Gateway when you activate the rule.

This section explains the steps to configure conditions and team names for creating a rule. Also, it lists the steps to activate rule to apply the rule to assets.

In this example, consider a team of users who must be enabled to view all assets. To achieve this, you can create a team called ViewAllAssets, and create a rule by selecting all assets and no conditions. When no conditions are specified, the rule is applied to all assets. When you activate this rule, all assets are assigned to the ViewAllAssets team.

The use case starts when you have a team and ends when you create a team assignment rule and activate the rule. All assets are assigned to the specified team and the team members can view all assets.

Before you begin

Ensure that you have:

• API Gateway administrator privileges.

• The team support feature enabled. For information on enabling the feature, see Enabling Teams Support.

• Ensure that the team, ViewAllAssets is created. For information on creating team, see Creating Teams.

To assign teams using team assignment rule

1. Expand the menu options icon , in the title bar, and select User management.

2. Click Global team assignments.

3. Click Add global team assignment.
   The Team assignment rule page appears.

4. Provide the name and description of the rule in corresponding fields.
   In this example, ViewRule is provided in the Name field.
   
   

5. Click Continue to filters >.

6. Select any or all assets in the Asset type field to apply the rule to the selected asset types.
   Available asset types are API, Application, Plan, and Packages.

7. Select any one of the following from the Logical operator field:

   • AND. To apply the rule only if all conditions are satisfied by an asset.

   • OR. To apply the rule when any of the given condition is satisfied by an asset.

8. To specify a condition based on the asset attributes, provide the following information, and click Add:

   Field	Description
   Attribute	Specifies the asset attribute. Available attributes: Name, Description, Tags. The global team assignment rule supports only API level tags. If you select multiple asset types, the tag filter is applicable to the API type alone and is not applicable for the for other asset types during filter evaluation.
   Operator	Comparison operator to validate the attribute against the given value. Available operators: Equals. Checks if the specified asset attribute is equal to the given value. Contains. Checks if asset contains the given value as a part of its name, description, or tag. Start with. Checks if asset name , description, or tag starts with the given value. Ends with. Checks if asset name , description, or tag ends with the given value.
   Value	Value of the attribute.

   For this use case, the rule has to be applied to all assets irrespective of their attributes. So, all asset types are selected and no condition is specified.
   
   

9. Click Continue to assign teams >.

10. Provide the required team names in the Name field.
    For our use case, the ViewAllAssets team is selected.
    
    

11. Click Save.
    The rule appears in the Global team assignment page.

12. Click the toggle button, adjacent to the rule.
    
    
    
    The rule is activated and applied across all existing assets. As per the rule, all assets are assigned to the ViewAllAssets team.

13. Click APIs from the title bar and select DevAPI.
    The API details page for the API appears.
    Note that the API is assigned to the ViewAllAssets team as per the ViewAssetsRule.
    
    

How do I Modify Teams Assigned to an API?

This use case explains how to modify the list of teams associated with an API. You can configure an approval process for the modification teams assigned to an API, if required. You can only assign the API to the teams that you are part of. However, you cannot remove the Administrators team and the teams that are assigned to an API using global assignment rules.

The use case starts when you have an API that requires a modification in the list of teams assigned to it and ends when you successfully make the change.

In this example, an API API is assigned to the Administrator team (by default). The API has to be assigned to the API-Gateway-Providers team along with the existing team through an approval process.

Before you begin

• Ensure that you have the change owner or team privilege.

• The change owner approval process configured and enabled if you want to enforce an approval process for ownership changes of assets. For details on configuring the approval process, see How Do I Configure the Approval Process for Ownership Change of Assets?

To modify the teams of an API

1. Log on to API Gateway as a user with the change ownership or team privilege.

2. Click APIs on the title navigation bar.

3. Click API.
   The API details page appears. The asset we have considered for example is not assigned to any team. So, the default team Administrators is displayed in the Team field of the Basic information section.
   
   

4. Click change.

5. Select the team that you want to assign and click . In this example, select the team API-Gateway-Providers.
   
   

   The change approval process is initiated.

   Note

   If the approval flow is not configured, the API-Gateway-Providers team is added and a success message appears. Skip to step 8.

6. An approval request is sent to the approver.

7. The approver approves the request that resides in the Pending Requests section of the API Gateway UI.

   Note

   The approver can click Reject to reject the request for ownership change if the request is invalid. A reject notification is sent to the requester and the team remains unchanged.

8. Click Change ownership request details to view the request details. The Request details dialog box appears.
   The approval notification is sent to the requester.
   The API-Gateway-Providers team is added.
   
   

How do I Change the Ownership of Multiple Teams?

You can change the owners of multiple teams in a single step. This use case explains how to change the ownership of multiple teams by sending a REST request. You can configure an approval process, if required, for the change of ownership to take effect.

The use case starts when multiple teams require change of owner and ends when you successfully change the ownership of the teams.

To change the ownership of multiple teams

1. Use the following REST request to change the asset ownership to a new user.

   POST http://hostname/rest/apigateway/assets/team
   Content-Type: application/json
   {
   	"assetType": "*", (API/APPLICATION)
   	"assetIds": ["*"],
   	"currentTeams": "team1",
   	"newTeams": ["team2"]
   }
   

   Provide the following information in the REST request:

   • assetType. Specifies the asset type for which you want to assign new teams. Available values are API, APPLICATION, or the wildcard *. The wildcard * specifies all the assets, APIs and applications owned by the user specified in currentTeams.

   • assetIds. Specifies the ID of the assets specified in assetType.

   Note

   This is optional. assetIds is not required if you specify currentOwner.
   • currentTeams. Specifies the current teams of the assets specified in the assetType field.
     
   Note

   If both currentTeams and assetIds are specified, both are validated. For example, consider user1 and user2 are owners of assetID1 and assetID2 respectively. In the request payload, if you include assetID1 and assetID2 in the assetIds field and user1 in the currentTeams field, then only assetID1 ownership changes.
   • newTeams. Specifies the teams to which you want to assign the specified assets.
     
     

   Example: If all APIs assigned to the DevTeam must be assigned to two other teams, Team2 and Team3, then send a REST request as follows:

   POST http://localhost:5555/rest/apigateway/assets/team
   Content-Type: application/json
   {
       "assetType": "*", (API/APPLICATION)
       "currentTeams": "DevTeam",
       "newTeams": ["Team2", "Team3"]
           
   }
   

   This request assigns the all APIs of DevTeam to Team2 and Team3. The change approval process is initiated.

2. An approval request is sent to the approver.
   The approval request contains information of all the assets whose ownership needs to change and the new owners’ name.

3. The approver approves the request in the Pending Requests section of the API Gateway UI.
   The approval notification is sent to the requester.

4. All APIs that are assigned to the DevTeam is assigned to Team2 and Team3.

Team Support Considerations

This section lists the impact of the Team support feature on other API Gateway features.

As stated in previous sections, users can view only the assets that are assigned to their teams. Also, their accessibility depends on the functional privileges assigned to their team. Though this appears to be a simple behavior, there are some scenarios where it gets a little exceptional. Hence, as an administrator, read through the following scenarios carefully before you create team and assign functional privileges:

Visibility and Accessibility of Assets

You can use the Teams support feature to restrict the visibility and access of APIs, applications, packages, and plans. However, there are some scenarios where users from unassigned teams can view or access these assets. Also, note that the Teams support feature does not restrict the visibility and access of aliases, global policies, scopes, users, groups, and teams.

Scenarios that you must consider when using Team support

1. When an API assigned to a team is associated with applications that are assigned to some other teams, then the team members, to whom the API is assigned can view the applications and remove them if required.

   For example, consider two teams Team_A and Team_B. The API API_1 and Application_1 are assigned to Team_A and the API API_2 and Application_2 are assigned to Team_B. If you associate Application_1 and Application_2 with API_1, then the Team_A members can view Application_2 and remove the application from API_1, if required.

2. Users can view assets other than APIs, applications, packages, and plans based on their functional privileges. So, the Team support feature does not have an impact on assets like aliases, global policies, scopes, users, groups, and teams.

   For example, consider two APIs, API_1 and API_2 assigned to two different teams; API_1 assigned to Team_A and API_2 assigned to Team_B. Consider a global policy applied to both APIs and an endpoint alias used in both APIs. In this case, users from both teams can view the global policy and the endpoint alias used by these APIs and there is no way to restrict this behavior.

The following table helps you to quickly recall the points discussed earlier in this topic:

Importing and Exporting of Teams and Assets

Team members can import or export assets if they are assigned with the required functional privileges.

• When assets are exported, the respective team details are exported along with the assets; members of the teams are not exported.

• When assets are imported, the respective team is created if it is not present already; members of the teams cannot be imported.

• When team is exported, the users and groups that are part of team can be selected for export if required.

• When team is imported, the users and groups are imported along with the team.

• An export archive of an API will include the details of all associated applications (if this option was selected when exporting) - “visible” and “invisible”

  An export archive of an Application will always include the details of all associated APIs - “visible” and “invisible”

Promotion management

Users with Manage promotions privilege can see all associated APIs/Applications (visible and invisible) on the Assets and dependencies page for the Applications/APIs selected on the Search page of the Promotion Management wizard

By switching between the Search page and the Assets and dependencies page using the Back and Next buttons, they can even drill down and recursively see all dependent assets (visible and invisible)

Members of a team can promote assets from one source stage to one or more target stages if they have the required functional privileges.

• When assets (all except teams) are promoted, they are promoted along with their team details; users are not promoted.

• When teams are promoted, the users and groups of teams can be promoted if required.

Scope mapping

Users with Manage scope mapping privilege can see all APIs (including APIs otherwise invisible to them) on the scope mapping configuration page. They can even add them to a scope mapping, but they cannot remove them again

Scope mappings are visible to all users

• API Gateway displays the names, descriptions, and versions for all associated APIs.
• The API entries are not linked with the respective API details pages

Note that there will be a scope mapping for every API if pg_oauth2_createDefaultScopes is set to true, so every API is listed in the list of scope mappings - visible to all users

Global policies for APIs

Global policies are visible to all users

• API Gateway displays names, descriptions, and versions for all associated APIs (by the policy’s filter conditions)

• Only the entries for the visible APIs are linked with their API details pages

API mashup

Users can add APIs owned by you or assigned to your Team, but in an existing API Mashup, you can see the names, versions, selected resources and methods of all configured APIs - even those invisible to you.

API versioning

On the API details page (for a visible API version), the API Gateway displays all version numbers in the version drop-down list - for versions visible and invisible to the current user.

When the user selects an invisible version, API Gateway displays an error message.

Scenarios where you cannot use Teams support

This section explains the use cases that cannot be achieved using the Team support feature.

Scenario 1

The functional privileges assigned to a team applies across all assets assigned to the team. You cannot assign different functional privileges to access different assets. That is, if you assign the Manage APIs functional privilege to a team, then the team members can perform all API-related transactions with the APIs assigned to the team. Similarly, if you assign the Manage applications privilege to a team, then all members of the team can manage the applications assigned to them.

For example, if you assign the Manage APIs privilege to Team_A and assign two APIs API_1 and API_2, then all users of the Team_A can manage both the APIs. If you do not assign the Manage APIs privilege to Team_B and assign two APIs API_1 and API_2, then the Team_B members can only view the APIs. They cannot manage them.

This image describes the flow that you can achieve:

In the same example, you cannot allow Team_B members to view API_1 and to manage API_2. You cannot assign different access level for different assets.

This image describes the flow that you cannot achieve:

Scenario 2

The functional privileges assigned to a team apply universally across all users within the team, affecting all assets assigned to that team and extending beyond the assets directly assigned to it. In other words, if a user has certain functional privileges through one of their teams, and when the user is assigned to another team that does not have a particular functional privilege, the user retains the functional privileges assigned through the first team. You cannot assign different privileges to different assets.

Consider User_2 is a part of Team_B that has the Manage APIs privilege assigned with API_2. In this case, User_2 can manage API_2. At the same time, if User_2 is assigned to Team_C that does not have the Manage APIs privilege. If API_2 is assigned to Team_C, then User_2 can still manage API_2.

This image explains the flow that cannot be achieved:

Custom Domains

A custom domain is a unique name that identifies your website. There are scenarios where you do not want to expose the default domain provided by webMethods.io API Gateway. In such cases, you can customize the default tenant URL or domain and access the tenant using your own domain.

Use custom domains if you want to make your application accessible on your own domain. Custom domains direct requests to your own URL.

How to configure Custom Domains?

You can request for a custom domain name for your tenant. For example, if your company domain is abc.com, you can have the domain name as https://subdomain.abc.com. Contact Software AG Global Support for details on how to enable and configure the custom domain capability.

Steps to configure custom domains:

Custom domains can be configured in the following two ways:

1. Determine the number of domains to be configured for your account and the list of custom domains.
   The domain names are owned by you. You can configure multiple custom domains based on the request.

2. Decide the SSL certificate required, which depends on whether you want to protect a single domain, multiple subdomains of a domain, or multiple domain names.

3. Share the number of domains to be configured for your account and the list of custom domains with Software AG.

4. Obtain the SSL certificates from a Certificate Authority (CA) and determine the number and type of domains you want to be protected by the certificates.

5. Send the SSL certificates and Certificate Key to Software AG in base64 format to configure the certificates on the custom domain load balancer.

6. Software AG sends you the CNAME in return.
   Using the CNAME, configure your DNS to point to the custom domain load balancer.

7. After the configuration is completed, start using the custom domain to access webMethods.io API Gateway.

Checks for existing assets after configuring custom domains

• External endpoints change after the custom domain is configured, so you have to inform your partners about the new domain. In case of a single domain, the old URL used by the tenant will not be functional for both Runtime and UI.

• Verify all assets that expose endpoint URLs, for example, REST APIs, SOAP APIs, Services over HTTP, and so on.

• A few assets, for example, SOAP APIs and REST APIs may not work after the custom domain change as the endpoints change after the custom domain is configured, so you should inform your customers to update the endpoints.

• Upon request, customers can maintain their existing domain for the Runtime API while directing the user interface to a newly configured domain. This prevents any inconsistencies that impact customers utilizing the Runtime API.

• Renewal of certificate for custom domain depends on licence terms, in most cases, it would be 1 year.

Configuring Extended Settings

You must have the API Gateway’s manage user administration functional privilege assigned to configure the extended settings.

You can configure advanced parameter settings in the Extended settings section. These parameters affect the operation of your server. You must not change these settings unless requested to do so by Software AG Global Support. You can configure the watt parameter settings in this section.

To configure the extended settings

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > Extended settings.

3. Click Show and hide keys.
   This displays all the configurable parameters.
   

4. You can configure any of the following parameters in the Extended keys section by providing the required values. The configured values are listed under Extended settings at the top of the page.

   Parameter and Description
   allowEGInvokeOnly Specifies whether the SOAP APIs with Transport policy set to http, can be invoked using the reverse invoke method when you set the external port as https, and the Registration and Internal ports as http. Ensure you enable this setting in the system where the SOAP API is created. Note: This setting affects only the behavior of SOAP APIs. You can invoke the REST APIs using the reverse invoke method, irrespective of this setting, given the above said conditions are true. Possible values: true. You can invoke SOAP APIs using the reverse invoke method if the external port is set as https, and the Registration and Internal ports are set as http. false. You cannot invoke SOAP APIs using the reverse invoke method.
   allowExceedMaxWindowSize Specifies whether the number of records retrieved by Elasticsearch in a single request exceeds the configured value or not. Possible values: true. The number of records retrieved in a single request can exceed the maximum value configured in Elasticsearch. This is the default value. false. Displays an error message when the number of records retrieved in a single request exceeds the configured value.
   apiDocumentsRestrictedExtension Specifies the list of restricted file extensions to prevent users from uploading files with those extensions as the input document for an API. For example, a file with the .exe file extension could contain executable code that run on demand when it is downloaded. If files with the .exe file extension are restricted, users cannot upload a file with the .exe extension in API Gateway. By default, several standard file extensions are blocked, including any file extensions that are treated as executable files by Windows Explorer. The file extensions blocked by default are: .bat - Batch file .bin - Binary file .dll - Windows dynamic link library .exe - Executable program You can remove any or all of the default file extensions.
   apiDocumentsUploadSizeLimitInMB Specifies the maximum document size, in MB, that can be uploaded as an input document for an API. Default value is 5. This prevents users from uploading huge files that might slow down the system.
   apig_MENConfiguration_tickInterval Specifies the time interval (in seconds) between each interval processor iteration. The value, you provide, must be an evenly divisible fraction of the smallest policy interval, which is one minute. Default value is 15. Note: Exercise caution when you modify this setting as this is a system level setting.
   apig_rest_service_redirect Provide the value true to redirect the incoming service requests to one of the following directives that API Gateway supports in addition to the /gateway directive: /ws /mediator The default value is false.
   apig_schemaValidationPoolSize Provide a value that specifies the schema validation pool size. The default value is 10.
   apiGroupingPossibleValues Specifies the names of API groups. You can organize your APIs by associating them to the relevant API groups. The groups provided, by default, are: Finance Banking and Insurance Sales and Ordering Search Transportation and Warehousing You can add, edit, or delete API groups based on your requirement.
   apiKeyExpirationPeriod Specifies the time for which an API Key is valid. You can provide the value in seconds, minutes, days, months, or years. For example, 8 seconds, 8s, 10 months, 10m, 15 minutes, 15min. The expiration date is computed as follows: When a new application is created: Expiration date = The time when an application is created + The value specified in the apiKeyExpirationPeriod parameter. When an API access key is regenerated: Expiration date = The time when the API key is regenerated + The value specified in the apiKeyExpirationPeriod parameter. If you do not specify a value, then the API key never expires.
   apiKeyHeader Specifies the HTTP header name from which API Gateway retrieves the API Key from incoming client requests. The default value is x-Gateway-APIKey.
   apiMaturityStatePossibleValues Specifies the API maturity state values that can be set for an API. You can search for APIs based on their maturity status. The default values provided are Beta, Deprecated, Experimental, Production, and Test.
   appMesh.microgateway.logLevel Specifies the log level of Microgateways that are deployed through API Gateway. The default value is ERROR. Possible values: TRACE, DEBUG, INFO, WARN, ERROR, FATAL.
   clusterNotifierCacheStaleInterval Specifies the time interval after which data in the ClusterNotifierCache is considered stale and is removed from the cache. The default value is 900 seconds. If you provide a non-numeric value, API Gateway interprets the value as the default value of 900 seconds. If you provide a value less than 60 seconds, API Gateway interprets the value as the lower limit of 60 seconds. The ClusterNotifierCache maintains a data structure which has an entry for each active member in a cluster. This data structure is used to communicate changes on API definitions, applications, policies, and so on, between the cluster members. When a cluster member shuts down gracefully it removes its entry from the data structure. However, when a cluster member process is killed the entry remains, and other cluster members continue posting notifications to the entry. In order to avoid endless growing resulting in performance degradation the cluster data structure is monitored for absent cluster members. If a cluster member has not reacted within the configured clusterNotifierCacheStaleInterval it is regarded as stale, and its data is removed from the ClusterNotifierCache.
   decodeAllDelimitersInURI Specifies whether the encoded characters of URL in the incoming client requests must be decoded or not. The URLs are encoded as per the URI specs or user’s requirements. Possible values: true. The encoded characters in the URL of incoming requests are decoded. false. The encoded characters in the URL of the incoming client requests are not decoded. This is the default value.
   defaultSearchResultSize Specifies the default size in the search request for the events, and metrics data. The default value is 1000. If you provide a value -1 it displays all the search results.
   disableRemoteEntityReference Specifies whether remote entity references are resolved when creating a SOAP API. Possible values: true. Disables the resolving of remote entity references when creating SOAP APIs. false. Enables the resolving of remote entity references when creating SOAP APIs.
   enableHotdeploy Specifies whether the hot deploy functionality is enabled. When this feature is enabled, you can modify active APIs. The default value is ‘true’. Possible values: true. Enables the hot deploy function. This is the default value. false. Disables the hot deploy function. Note: Ensure to refresh your browser when you modify this setting to reflect the changes to the ongoing user sessions.
   enableImportBackup Provides an option to secure an API before overwriting it. Available values are: true. If you set the value to true, the existing API is restored in the event of an error during the import. This is the default value. false. If you set the value to false, the feature to secure an existing API before overwriting is disabled. If the overwrite fails due to an error during the import, the existing API has to be deleted.
   enableTeamWork Specifies whether the Team Support feature in API Gateway is enabled. Possible values: true - enables the Team Support feature. false - disables the Team Support featured. This is the default value.
   esScrollTimeout Specifies the time, in milliseconds, that the search results for each request must be kept active in Elasticsearch. When the allowExceedMaxWindowSize setting is enabled, the Scroll feature of the Elasticsearch is enabled to allow Elasticsearch to accept multiple search requests and return multiple results. That is, you can perform multiple search requests using the same query till you get the desired number of records from Elasticsearch. When you send a search request, Elasticsearch returns the result and keeps the result active for the time specified in the esScrollTimeOut setting. If a request exceeds the time specified in the esScrollTimeOut setting, then the subsequent search requests also fail with a Invalid Scroll ID error message. For more information on the Scroll feature, refer https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-scroll.
   eventsRefreshInterval Specifies the default refresh interval for the events indices in seconds. The default value is 10 seconds.
   forwardInternalAPIsRequest This parameter is required in the case of a paired gateway deployment scenario using an Advanced Edition license at DMZ. Specifies whether the incoming requests are forwarded to internal APIs that are deployed in the green zone. Possible values: true. API Gateway forwards the incoming requests to the internal APIs that are deployed in the green zone false. API Gateway does not forward the incoming requests. This is the default value. Following are the internal APIs and their URIs for which this parameter is required and its value must be set to true: getOAuthToken - /pub/apigateway/oauth2/getAccessToken OAuth Authorization - /pub/apigateway/oauth2/authorize getOpenIdToken - /pub/apigateway/openid/getOpenIDToken openIDCallbackService - /pub/apigateway/openid/openIDCallback getJWTToken - /pub/apigateway/jwt/getJsonWebToken
   forwardQueryParams Specifies whether API Gateway should forward the query parameter sent by client and query parameters configured in Request Processing stage to the native service if the ${sys:resource_path} variable is not present in the Routing policy URL. true. API Gateway forwards the query parameters sent by client and query parameters configured in Request Processing stage to the native service even if the ${sys:resource_path} is not present in the Routing policy URL. false. API Gateway does not forward the query parameters to the native service if the ${sys:resource_path} is not available in the Routing policy. This is the default value.
   gatewayClientInvokingToken Specifies the value of the client token that can invoke the backend APIs in API Gateway. The default value is apigateway.
   maxAllowedZipFileSize Specifies the maximum size of the zip file that can be uploaded to create an API from the Create API screen. Default value is 100000000.
   maxRegexLengthInSearchQuery Specifies the maximum length of Regex parameter that you can use in Regex expression query. Default value is 37000. This value can be increased based on the requirement.
   maxWindowSize Specifies the maximum number of search results that Elasticsearch can return for a single search request. Using the index.max_result_window property in Elasticsearch, you can configure the maximum number of records to be retrieved in a single Elasticsearch request. To know more about the property, refer https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html. Default value is 10000. If the value configured in the index.max_result_window setting of Elasticsearch is different from that of the default value, then it is recommended that you provide the same value in this field. If you have a value greater than the configured value, then Elasticsearch displays an error message. Also, you must enable the allowExceedMaxWindowSize setting if the total number of results to be retrieved is more than the value specified here. For example, if you have specified 1000 in this setting and the total number of records to be retrieved is 20000, then API Gateway sends 20 requests to retrieve all records provided the allowExceedMaxWindowSize setting is enabled. In the above example, if the allowExceedMaxWindowSize setting is not enabled, an error message is displayed as the value is lesser than the default value.
   numberOfTokensToCacheLocally Specifies the number of tokens to be cached locally before accessing the cluster for more tokens to serve the next set of requests. When a node recieves a request, a locally cached token serves the request. Locally caching tokens avoids access to the cluster for each invocation. Specify a value greater than 0 tokens to cache locally. If you do not specify this value, the node has to access the cluster to get token for each invocation. API Gateway fetches a new set of tokens from the cluster, if: All cached tokens are used. The validity of tokens is over. The default value is 0.
   paginationPossibleValues Specifies the list of possible values of the pagination size, that is, number of items listed per page. The default values displayed for pagination options are 10,20,30,40,50. For example, if you select 20, then 20 items are displayed per page. For example, if you change the values to 5,10,15,20,25 then pagination options displayed are 5, 10, 15, 20 and 25. So now when you select 15, the items displayed per page would be 15. On modifying the value, you have to logout and re-login for the changes to reflect.
   pg_Dataspace_GossipInterval Specifies how frequently each node should gossip with one another. By default, the value is set to 3 seconds.
   pg_Dataspace_TimeToFail Specifies the maximum permissible interval between two consecutive gossips. By default, the value is set to 30 seconds.
   pg_Dataspace_WarmupTime Specifies the maximum permissible rehashing interval from start-up or shut down of the server. By default, the value is set to 300 seconds.
   pg_JWT_isHTTPS Specifies whether the transport protocol over which the JSON Web Tokens (JWTs) are granted authorization. Possible values: true. Sets the transport protocol HTTPS. This is set by default. false. Sets the transport protocol HTTP.
   pg_oauth2_createDefaultScopes Specifies whether to create a default scope. Possible values: true. When you set this to true and local authorization server is configured as the default authorization server, then API Gateway automatically creates a scope in Integration Server during API creation, and creates a scope mapping between the OAuth scope in the local authorization server and the API. This setting is useful in cases where a service is published from Centrasite. false. When you set this to false, API Gateway does not create a scope automatically. Users must manually create and map scopes for the services published from Centrasite. This is the default value.
   pg_oauth2_isHTTPS Specifies the transport protocol over which the OAuth 2.0 access tokens are granted authorization. Possible values: true. Sets the transport protocol HTTPS. This is set by default. false. Sets the transport protocol HTTP.
   pg_OpenID_isHTTPS Specifies the transport protocol over which the OpenID (ID) tokens are granted authorization . Possible values: true. Sets the transport protocol HTTPS. This is set by default. false. Sets the transport protocol HTTP.
   pg_xslt_disableDoctypeDeclarations Disables the xslt doc type declarations. The default value is true.
   pg_xslt_enableDOM Provide the value true to enable DOM parsing. The value false disables the DOM parsing and enables other parsers
   pg_xslt_enableSecureProcessing Provide the value false to disable the use of extensions by default. The default value is true.
   pg.cs.snmpTarget.connTimeout Specify the number of milliseconds before an inactive connection to the SNMP target server is closed. If set to 0, the socket remains open indefinitely.
   pg.cs.snmpTarget.maxRequestSize Specify the maximum size (in bytes) for SNMP traps. The default value is 10485760.
   pg.cs.snmpTarget.retries Specifies the number of times to resend SNMP traps upon failure. Default value is 1. This parameter works with pg.cs.snmpTarget.sendTimeOut to determine the delay in re-sending SNMP traps to malfunctioning SNMP servers (that is, it retries*sendTimeOut). This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
   pg.cs.snmpTarget.sendTimeOut Specify the time (in milliseconds) to wait before the SNMP trap times out because the server destination is not responding. This value schedules a timer that resends an SNMP event that has not yet completed when it expires. You must set a timeout value that ensures that the trap is sent to the SNMP server within the time frame. This parameter does not abort an event that is in progress. Set this parameter higher than the default when sending traps with large payloads. The default value is 500. This parameter works with pg.cs.snmpTarget.retries to determine the delay in resending SNMP traps to malfunctioning SNMP servers (that is, it retries *sendTimeOut). This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
   pg.default.enable.oldVersion Specifies whether the oldest version of an API has to be enabled when the version of an API is not specified. For example, when you have an API that is versioned, the client can specify the version number in the URL to invoke that specific version of the API, that is, API-NAME/Version-number. When the client does not specify the version number, API Gateway defaults to the latest version of the API and invokes it. You can use this parameter to change this behavior such that API Gateway defaults to the oldest version of API and invokes it. Available values are: true. When you set this parameter as true and invoke an API without specifying the version number, then API Gateway defaults to the oldest version of the specified API and invokes it. false. This is the default value. When you set this parameter as false and invoke an API without specifying the version number, then API Gateway defaults to the latest version of the specified API and invokes it.
   pg.endpoint.connectionTimeout Specifies the time interval (in seconds) after which an HTTP connection attempt times out. The default value is 30 seconds. This is a global property that applies to the endpoints of all APIs. If you prefer to specify a connection timeout for the endpoints of an API individually, set the HTTP Connection Timeout parameter in the API’s Routing Protocols processing step, which would then take precedence over pg.endpoint.connectionTimeout. The precedence of the Connection Timeout configuration is as follows: 1. If you specify a value for the Connection timeout field in routing endpoint alias, then the Connection timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level. 2. If you specify a value 0 for the Connection timeout field in routing endpoint alias, then API Gateway uses the value specified in the Connection timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration. 3. If you specify a value 0 or do not specify a value for the Connection timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.connectionTimeout property. 4. If you do not specify any value for pg.endpoint.connectionTimeout, then API Gateway uses the default value of 30 seconds.
   pg.endpoint.readTimeout Specifies the time interval (in seconds) after which a socket read attempt times out. Default value: 30 seconds. This is a global property that applies to all APIs. If you prefer to specify a read timeout for APIs individually, set the Read Timeout field in the API’s’s Routing Protocols processing step, which would then take precedence over pg.endpoint.readTimeout. The precedence of the Read Timeout configuration is as follows: 1. If you specify a value for the Read timeout field in routing endpoint alias, then the Read timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level. 2. If you specify a value 0 for the Read timeout field in routing endpoint alias, then API Gateway uses the value specified in the Read Timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration. 3. If you specify a value 0 or do not specify a value for the Read timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.readTimeout property. 4. If you do not specify any value for pg.endpoint.readTimeout, then API Gateway uses the default value of 30 seconds.
   pg.lb.failoverOnDowntimeErrorOnly Specifies API Gateway’s behavior of endpoints in a load-balanced routing scenario. Possible values: true. Load balancing does not happen when the service fault encountered in the response is a downtime error. This is the default value. For example, the following are some Downtime exceptions and for which fail overs happen: ConnectException, MalformedURLException, NoRouteToHostException, ProtocolException, SocketTimeoutException, UnknownHostException, UnknownServiceException, Web Service not available, The service cannot be found. false. Load balancing happens whenever a service fault is encountered in the response coming from endpoint 1 and API Gateway immediately tries the next configured endpoint. There is no distinction on the type of fault present in the response from endpoint.
   pg.MTOMStreaming.cachedFiles.delete.interval Specifies the interval (in seconds) to delete the cached MTOM files. Default value is 3600 seconds. This property takes effect only when the pg.suppress.IS.lcm setting is set to true.
   pg.nativeServer.validatePrivateIPs Specifies whether to validate the native server endpoint against the private IP configuration during invocation of an API. Possible values: true. If this is set to true, then the API invocation is not allowed if the native endpoint uses any private IPs other than the ones configured in /rest/apigateway/configurations/whiteListingIPs false. If this is set to false, no private IP validation is done for the native endpoint. Default value is false for on-prem and true for cloud installations.
   pg.overwrite.users.withsameloginid Specifies whether API Gateway must validate and overwrite a user based on their login ID or UUID when importing or promoting the user or team from one stage to another, provided the logged-in credentials (login ID) of both instances are the same. Possible values: true. API Gateway validates and overwrites the user with the user’s login ID, if the user is not matched with the UUID during import or promotion of a user or teams. The default value is true. false. API Gateway validates and overwrites the user with the UUID.
   pg.removeSSNID Specifies whether to include the set-cookie header in the response header. The set-cookie header contains ssnid value sent from the native service. Possible values: true. The client that invokes API Gateway API, does not receive the set-cookie header that contains ssnid value. false. The client that invokes API Gateway API, receives the set-cookie header that contains ssnid value if the native service sends this in the response.
   pg.security.honourPortAccessModeSettings Specifies whether the access mode settings configured in the Administration > Security > Ports section must be enforced on the HTTP and HTTPS ports. In addition to the default port, you can add ports in API Gateway using which you can consume APIs. You can configure the access mode of the ports to determine whether a port can be used to access an API or not. You can either allow or deny the access of all APIs through a port. When you allow access of APIs using a port by default, you can specify a list of APIs that must be denied access over the port. Also, if you deny the access of APIs using a port, you can specify a list of APIs that an be allowed to access using the port. You can use the pg.security.honourPortAccessModeSettings setting to configure whether the access mode configured from the Ports section must be enforced on the HTTP and HTTPS ports or not. This configuration is applicable only for REST and OData APIs. Possible values: true. Access to the HTTP and HTTPS ports is allowed or denied based on the settings in the Administration > Security > Ports section. false. The access mode setting specified for the ports are not applied. This is the default value.
   pg.snmp.communityTarget.base64Encoded Specify whether to use a third-party SNMPv1 community-based connection. If set to true, the community name must be the Base64 value. The default value is false.
   pg.snmp.communityTarget.maxRequestSize Specifies the maximum size (in bytes) for SNMP traps. The default value is 65535.
   pg.snmp.communityTarget.retries Specifies the number of times to resend SNMP traps upon failure. Default value is 1. This parameter works with pg.snmp.communityTarget.sendTimeOut to determine the delay in re-sending SNMP traps to malfunctioning SNMP servers (that is, it retries *sendTimeOut). This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
   pg.snmp.communityTarget.sendTimeOut Specifies the time (in milliseconds) to wait before the SNMP trap times out because the server destination is not responding. This value schedules a timer that resends an SNMP event that has not yet completed when it expires. You must set a timeout value that ensures that the trap is sent to the SNMP server within the time frame. This parameter does not abort an event that is in progress. Set this parameter higher than the default when sending traps with large payloads. The default value is 500. This parameter works with pg.snmp.communityTarget.retries to determine the delay in re-sending SNMP traps to non-responsive SNMP servers (that is, it retries *sendTimeOut). This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
   pg.snmp.customTarget.connTimeout Specify the number of milliseconds before an inactive connection to the third-party SNMP server is closed. If set to 0, the socket remains open indefinitely.
   pg.snmp.userTarget.maxRequestSize Specify the maximum size (in bytes) for SNMP traps. The default value is 65535.
   pg.snmp.userTarget.retries Specifies the number of times to resend SNMP traps upon failure. The default value is 1. This parameter works with pg.snmp.userTarget.sendTimeOut to determine the delay in re-sending SNMP traps to malfunctioning SNMP servers (that is, it retries *sendTimeOut). This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
   pg.snmp.userTarget.sendTimeOut Specifies the time (in milliseconds) to wait before the SNMP trap times out because the server destination is not responding. This value schedules a timer that resends an SNMP event that has not yet completed when it expires. You must set a timeout value that ensures that the trap is sent to the SNMP server within the time frame. This parameter does not abort an event that is in progress. Set this parameter higher than the default when sending traps with large payloads. The default value is 500. This parameter works with pg.snmp.userTarget.retries to determine the delay in resending SNMP traps to malfunctioning SNMP servers (that is, it retries *sendTimeOut). This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
   pg.soapToRest.typeConvertorEnabled Specifies whether the key values in a SOAP request must be converted to their primitive type when a SOAP API is transformed to REST API. For example, if the XML is 10, it is converted as “number” : 10. Possible values: true. Values are converted to their primitive type. This is the default value. false. Values are not converted to their primitive type.
   pg.suppress.IS.lcm Specifies whether to override IS lifecycle manager with API Gateway lifecycle manager. Possible values: true. Set this to true to use theAPI Gateway lifecycle manager. false. Set this to false to use the IS lifecycle manager By default, the value is false. API Gateway lifecycle manager provides options to specify the interval for deleting of cached MTOM files using the pg.MTOMStreaming.cachedFiles.delete.interval setting.
   pgmen.quotaSurvival.addLostIntervals Specifies whether the lost intervals from the recovered quota should be added.
   pgmen.quotaSurvival.interval Specifies the number of seconds that elapses before the quota survival processor task runs.
   promotionListSortByTime Specifies whether the list of promotions in the Promotions tab of the Promotion management page are sorted by the promotion time. Possible values: true. Promotion list is sorted by promotion time with the latest on top. false. Promotion list is sorted by promotion name. This is the default value.
   retainResponseStatus Specifies whether the native service status has to be modified before sending it to client. The default value is false, which specifies that if the outbound authentication-custom credentials or delegate incoming credentials are configured with incorrect credentials the native service status is changed before sending it to client. If this value is set to true, it specifies that the status received from the native service is sent without modifying it.
   return408ForConnectionTimeout Specifies the status code to be included in the response when a request to the native service times out. Possible values: true. The response contains 408 error code uniformly when a request to the native service is timed out. This is the default value. false. The response does not contain 408 error code.
   saveAuditlogsWithPayload Specifies whether the audit logs have to be saved along with payload. Possible values: true. The audit logs have to be saved along with payload. This is the default value. false. The audit logs are not saved along with payload.
   sendClientRequestURI Specifies whether the URI that is present in a request must be decoded before sending it to the native service. Possible values: true. The URI is not decoded. The unicode characters in a request are encoded. false. The URI is decoded without change in the path of the URL. This is the default value.
   startDayOfTheWeek Specifies the start day of a week for the unit of measurement of the Alert Interval configured, to monitor performance, before sending an alert. By default, the start day of the week is set to Monday. Note: If you modify this value, you must restart API Gateway for the modified value to take effect. Please contact Software AG Support team to restart the API Gateway server.
   setDefaultContentType Specifies that default content type to be included in the GET and DELETE methods, if the content type is missing in request. Possible values: true. The default content type application/x-www-form-urlencoded is added, if content type is missing in request. This is the default value. false -The default content type is not added. The content-type is sent as is.
   strictResourceMatching Specifies whether API Gateway must perform a strict matching of the resource path from runtime invocation with the API definition of resource paths. Possible values: true. API Gateway uses the strict resource matching criteria and the matching fails if it encounters any other characters than that are specified. This is the default value. false. API Gateway matches the best resource instead of using the strict resource matching criteria. This extended setting functions as follows: For example, consider a REST API with resource path /mypath The request http://host:port/servicename/mypath/anytext with strictResourceMatching=true returns an HTTP response 404 immediately. The request http://host:port/servicename/mypath/anytext with strictResourceMatching=false executes the request in an ordinary way.
   tagsTypeAheadSearchResultSize Specifies the number of existing tags to display during the type ahead search. This is available while adding a tag to an API, where you can type a search term. A list of existing API tags appears depending on the search term. The number of API tags displayed in this list is restricted as per the value provided in the tagsTypeAheadSearchResultSizeproperty. The default value is 10. The minimum value you can provide is 1. If you provide zero or an invalid value, the value of this property is set to the default value 10.
   transferEncodingChunked_handleAsStream Specifies whether the request payload should be handled as stream when the request contains Transfer-Encoding:chunked header. The default value is false. The behavior is as follows depending on the value provided for this setting: If Transfer-Encoding: chunked header is sent in the request and the extended setting transferEncodingChunked_handleAsStream is set as true, the request payload is handled as stream. If Transfer-Encoding: chunked header is sent in the request and the extended setting transferEncodingChunked_handleAsStream is set as false, the request payload would be handled as is (no streaming). If Transfer-Encoding: chunked header is not sent in the request, the request payload is handled as is (no streaming). If Transfer-Encoding: chunked header is not sent in the request and the extended setting transferEncodingChunked_handleAsStream is set as true, the request payload is handled as is (no streaming).
   transformerPoolSize Specifies the maximum size for transform pool that consists XSLT transformers. To reduce performance impacts, you can reuse the transformers from the pool instead of creating them for every request.
   useTypeInIndexNameForESDestination Specifies the index format used when sending data from API Gateway to a configured Elasticsearch destination. The default value is true. Elasticsearch verison 7.2 supports data with dedicated index for each of the event types. So, API Gateway sends data in different indexes for different event types if the value of this property is set to true. The event type is concatenated with the Elasticsearch destination index name. That is, the index name will be in the following format: {IndexName}_{EventType}. For example, database_transactionalevents; where default is the index name and transactional events in the event type. If the value is set to false, the type name is not concatenated with the index name. In this case, the index created for each event is sub-indexed under a main index when data is sent to configured Elasticsearch destination. The value of this setting must be set to false, if the version of the destination Elasticsearch is 5.x or earlier.
   xmlToJSONConversion_keepString Specifies whether the data type of fields in a response payload, after XML to JSON conversion, must be string or a corresponding data type. The default value is true. Possible values: true. The data type of the fields is retained as string. false. The data type of the fields is changed to a corresponding data type. For example: Sample XML payload: <?xml version="1.0" encoding="UTF-8"?> <EmployeeDetail> <ID>12345</ID> <Name>John</Name> <Address>999 ABC Street</Address> </EmployeeDetail> Sample response, if you set the extended setting to true: { "EmployeeDetail": { "ID": "12345", "Name": "John", "Address": "999 ABC Street" } } All fields in the response payload are retained as string. Sample response, if you set the extended setting to false: { "EmployeeDetail": { "ID": 12345, "Name": "John", "Address": "999 ABC Street" } } The data type of the field ID is integer.

5. You can configure the watt parameters in the Watt keys section by providing the required values.
   The configured watt keys are listed under Watt settings below the Extended keys at the top of the page. Only the following watt parameters get synchronized across nodes in a cluster setup:

   • watt.security.ssl.client.ignoreEmptyAuthoritiesList.
   • watt.security.ssl.ignoreExpiredChains.
     
   • watt.server.url.alias.partialMatching.
     
   • watt.server.oauth.authServer.alias
     
   • watt.server.oauth.requireHTTPS
     
   • watt.net.http401.throwException
   • watt.net.http501-599.throwException
   • watt.server.SOAP.MTOMStreaming.enable
   • watt.server.http.Strict-Transport-Security
     
   • watt.server.rest.removeInputVariablesFromResponse
   • watt.server.coder.responseAsXML
   • watt.security.ssl.cacheClientSessions
   • watt.server.enterprisegateway.ignoreXForwardedForHeader

   If you modify the other watt parameters in one API Gateway instance they do not get synchronized across other nodes in a cluster setup. You have to manually modify them in the other instances.

6. Click Save.

Configuring API Fault Settings

You must have the API Gateway’s manage user administration functional privilege assigned to configure the API fault settings.

You can configure global error responses for all APIs to display the default error message.

To configure the service fault settings

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > API fault.

3. Select Send native provider fault to send the native API provider’s fault content, if available. API Gateway ignores the default error message and sends whatever content it receives from the native API provider. If you do not select this option then API Gateway sends the default error message.
   

4. Specify the error message text in the Default error message text box that is sent out when the Send native provider fault is not selected.

5. Click Save.

Approval Configuration

API Gateway allows you to configure an approval process to ensure that the requests are valid. If the requests are invalid, API Gateway enables approvers to reject the requests. API Gateway allows you to configure approvals for:

• Create application: To enforce approvals for creating an application in API Gateway.

• Register application: To enforce approvals for associating an application with APIs.

• Update application: To enforce approvals for modifying an application.

• Subscribe package: To enforce approvals in API Gateway to enable Developer Portal consumers for subscribing a package to a plan in Developer Portal.

In API Gateway, you can create an application and associate (register) the application created with APIs. If you have the API Gateway’s manage general administration configurations functional privilege assigned, you can configure approvals for creating or registering an application. If you have configured approvers, and if a user wants to create and register an application in API Gateway, then the application is created and registered with an API only if any one approver from the approvers group approves the create application and the register application requests. Similarly, you can configure approvals for updating an application or subscribing a package.

You can configure a set of different approvers for creating or registering applications. For example, if you have configured an approvers group, group1 to approve or reject a create application request and an approvers group, group2 to approve or reject a register application request, then when a user creates and registers an application in API Gateway, then the create application request must be approved by any one approver in group1. When the application is created, the register application request is sent to the approvers in group2 and this register application request must be approved by any one approver in group2. When the request is approved, the application created is registered to an API. However, if any one user from group2 rejects the request, then the application gets created but is not register to an API.

API Gateway approvals can also be used when API Gateway is integrated with Developer Portal and an Developer Portal API consumer uses the API get access token to register an application to an API in API Gateway. In this scenario, Developer Portal implicitly sends a request to API Gateway to create an application. When the approvers approve the create application request, an application is created in API Gateway and then API Gateway initiates a register application request and the approvers approve the register application request. The application is registered to an API which is published to Developer Portal. The consumer is now able to view and manage the API in Developer Portal.

Similarly, you can configure approvals for subscribing a package in API Gateway, when an API consumer subscribes to a package in Developer Portal. API Gateway receives the package subscription request and the approvers in the approvers group approve or reject the request for subscribing a package. When the request is approved, the acknowledgement is sent to Developer Portal and the package is subscribed.

Configuring Approvals for Creating Application

You have to configure the approval settings, to enforce approval for creating an application in API Gateway.

To configure approvals for creating an application

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > Approval configuration > Create application.

3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

4. Select the access profile of approvers from the Approvers drop-down list.

5. Select anyone from the Approved by drop-down list.
   This implies that, any one user of the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approvers group.
   

   Note

   If a user is associated with the selected team, then the user can approve or reject a pending request even if the user is not associated with the Approvers group.

6. Select the Team approvers option to allow the team approvers to approve the pending requests of applications that the team is associated with.
   You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
   If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

8. Select Configure approval initiate request mail template to be sent to approver.
   This is to configure the email template to be sent to the approver, for approving the request of creating an application.

9. Provide the following information in the Configure approval initiate request mail template to be sent to approver section:

   Field	Description
   Send notification	To send an email notification to the approver to approve the request for creating an application.
   Subject	The subject line of the email to be sent.
   Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID. For more infomration on supported variables see, Email templates variable.

   Note

   The email notifications are sent only to the local API Gateway users.

10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for creating an application is approved.

11. Provide the following information in the Configure request approved mail template to be sent to requester section:

    Field	Description
    Send notification	To send an email notification to the requester that the request for creating an application is approved by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Create Application in the email sent, where Create Application is the event.type. For more infomration on supported variables see, Email templates variable.

12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for creating an application is rejected.

13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field	Description
    Send notification	To send an email notification to the requester that the request for creating an application is rejected by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Create Application in the email sent, where Create Application is the event.type. For more infomration on supported variables see, Email templates variable.

14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

15. Click Save.

Configuring Approvals for Registering Application

You have to configure the approval settings, to enforce approval for associating an application with APIs in API Gateway. The Developer Portal API get access token request is considered as a create and registering application event in API Gateway.

To configure approvals for registering an application

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > Approval configuration > Register application.

3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

4. Select the access profile of approvers from the Approvers drop-down list.

5. Select the anyone from the Approved by drop-down list.
   This implies that, any one user of the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approvers group.

   Note

   If a user is associated with the selected team, then the user can approve or reject a pending request even if the user is not associated with the Approvers group.

6. Select the Team approvers option to allow the approvers of the team that owns the API being registered.
   You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have
   the privilege to approve application creation requests.
   If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

8. Select Configure approval initiate request mail template to be sent to approver.
   This is to configure the email template to be sent to the approver for associating an application with APIs.

9. Provide the following information in the Configure approval initiate request mail template to be sent to approve section:

   Field	Description
   Send notification	To send an email notification to the approver to approve the request for associating an application with APIs.
   Subject	The subject line of the email to be sent.
   Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.

   Note

   The email notifications are sent only to the local API Gateway users.

10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for associating an application with APIs is approved.

11. Provide the following information in the Configure request approved mail template to be sent to requestersection:

    Field	Description
    Send notification	To send an email notification to the requester that the request for associating an application with APIs is approved by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Register Application in the email sent, where Register Application is the event.type.

12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for registering an application is rejected.

13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field	Description
    Send notification	To send an email notification to the requester that the request for associating an application with APIs is rejected by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Register Application in the email sent, where Register Application is the event.type.

14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

15. Click Save.

Configuring Approvals for Updating Application

You have to configure the approval settings, to enforce approval for modifying an existing application in API Gateway.

To configure approvals for updating an application

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > Approval configuration > Update application.

3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

4. Select the access profile of approvers from the Approvers drop-down list.

5. Select anyone from the Approved by drop-down list.
   This implies that, any one user of the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approvers group.

   Note

   If a user is associated with the selected team, then the user can approve or reject a pending request even if the user is not associated with the Approvers group.

6. Select the Team approvers option to allow the team approvers to approve the pending requests of applications that the team is associated with.
   You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
   If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

8. Select Configure approval initiate request mail template to be sent to approver.
   This is to configure the email template to be sent to the approver for approving the request of modifying an existing application.

9. Provide the following information in the Configure approval initiate request mail template to be sent to approver section:

   Field	Description
   Send notification	To send an email notification to the approver to approve the request for modifying an existing application.
   Subject	The subject line of the email to be sent.
   Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.

   Note

   The email notifications are sent only to the local API Gateway users.

10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for modifying an existing application is approved.

11. Provide the following information in the Configure request approved mail template to be sent to requester section:

    Field	Description
    Send notification	To send an email notification to the requester that the request for modifying an existing application is approved by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Update Application in the email sent, where Update Application is the event.type.

12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for modifying an existing application is rejected.

13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field	Description
    Send notification	To send an email notification to the requester that the request for modifying an existing application is rejected by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Update Application in the email sent, where Update Application is the event.type.

14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

15. Click Save.

Configuring Approvals for Subscribing Package

You have to configure the approval settings in API Gateway, to enforce approval for subscribing a package to a plan in Developer Portal.

To configure approvals for subscribing a package

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > Approval configuration > Subscribe package.

3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

4. Select the access profile of approvers from the Approvers drop-down list.

5. Select anyone from the Approved by drop-down list.
   This implies that, any one user of the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approvers group.

   Note

   If a user is associated with the selected team, then the user can approve or reject a pending request even if the user is not associated with the Approvers group.

6. Select the Team approvers option to allow the team approvers to approve the pending requests of applications that the team is associated with.
   You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
   If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

8. Select Configure approval initiate request mail template to be sent to approver.
   This is to configure the email template to be sent to the approver for subscribing a package.

9. Provide the following information in the Configure approval initiate request mail template to be sent to approve section:

   Field	Description
   Send notification	To send an email notification to the approver to approve the request for subscribing a package.
   Subject	The subject line of the email to be sent.
   Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.

   Note

   The email notifications are sent only to the local API Gateway users.

10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for subscribing a package is approved.

11. Provide the following information in the Configure request approved mail template to be sent to requester section:

    Field	Description
    Send notification	To send an email notification to the requester that the request for subscribing a package is approved by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Subscribe Package in the email sent, where Subscribe Package is the event.type.

12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for subscribing a package is rejected.

13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field	Description
    Send notification	To send an email notification to the requester that the request for registering an application is rejected by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Subscribe Package in the email sent, where Subscribe Package is the event.type.

14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

15. Click Save.

Configuring Approvals for Updating Subscription

You have to configure the approval settings, to enforce approval to modify an existing subscription in API Gateway. When you request an approval for subscription update, the existing package and plan are in use, until an approver approves your request. Once the approver approves the change of subscription request, the quota is reset.

To configure approvals for updating a subscription

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > Approval configuration > Update subscription.

3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

4. Select the team of approvers from the Approvers drop-down list.

5. Select Anyone from the Approved by drop-down list.
   This implies that, any user associated with the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approver’s group.

   Note

   If a user is associated with the team, then the user can approve or reject a pending request.

6. Select the Team approvers option to allow the team approvers to approve the pending requests of applications that the team is associated with.
   You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
   If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

8. Select Configure approval initiate request mail template to be sent to approver.
   This is to configure the email template to be sent to the approver for approving the request of modifying an existing subscription.

9. Provide the following information in the Configure approval initiate request mail template to be sent to approver section:

   Field	Description
   Send notification	To send an email notification to the approver to approve the request for modifying an existing subscription.
   Subject	The subject line of the email to be sent.
   Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approver’s login ID.

   Note

   The email notifications are sent only to the local API Gateway users.

10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for modifying an existing subscription is approved.

11. Provide the following information in the Configure request approved mail template to be sent to requester section:

    Field	Description
    Send notification	To send an email notification to the requester that the request for modifying an existing subscription is approved by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Update subscription in the email sent, where Update subscription is the event.type.

12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for modifying an existing subscription is rejected.

13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field	Description
    Send notification	To send an email notification to the requester that the request for modifying an existing subscription is rejected by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Update subscription in the email sent, where Update subscription is the event.type.

14. Click Save.

Configuring Approvals for Deleting Subscription

You have to configure the approval settings, to enforce approval to delete an existing subscription in API Gateway. When you raise a deletion request, the application is suspended automatically. If an approver approves the deletion request, the subscription is deleted. However, if the approver rejects the request, subscription is enabled. When the application is suspended, if a user invokes the application, the quota usage for that application is continued to be calculated. This is a known issue and would be resolved in subsequent releases.

To configure approvals for deleting a subscription

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > Approval configuration > Delete subscription.
   

   

3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

4. Select the team of approvers from the Approvers drop-down list.

5. Select Anyone from the Approved by drop-down list.
   This implies that, any user associated with the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approver’s group.

   Note

   If a user is associated with the team, then the user can approve or reject a pending request.

6. Select the Team approvers option to allow the team approvers to approve the pending requests of applications that the team is associated with.
   You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
   If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

8. Select Configure approval initiate request mail template to be sent to approver.
   This is to configure the email template to be sent to the approver for approving the request of deleting an existing subscription.

9. Provide the following information in the Configure approval initiate request mail template to be sent to approver section:

   Field	Description
   Send notification	To send an email notification to the approver to approve the request for deleting an existing subscription.
   Subject	The subject line of the email to be sent.
   Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approver’s login ID.

   Note

   The email notifications are sent only to the local API Gateway users.

10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for deleting an existing subscription is approved.

11. Provide the following information in the Configure request approved mail template to be sent to requester section:

    Field	Description
    Send notification	To send an email notification to the requester that the request for deleting an existing subscription is approved by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Delete subscription in the email sent, where Delete subscription is the event.type.

12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for deleting an existing subscription is rejected.

13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field	Description
    Send notification	To send an email notification to the requester that the request for deleting an existing subscription is rejected by the approver.
    Subject	The subject line of the email to be sent.
    Content	By default, the template appears. You can customize the email content. Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Delete subscription in the email sent, where Delete subscription is the event.type.

14. Click Save.

Email templates variable

Approval Email Variables

Rejection Email Variables

How Do I Configure the Approval Process for Ownership Change of Assets?

If you want to enforce an approval process, configure and enable the approval process for ownership change of assets. The approver can approve or reject the request.

Before you begin

Ensure that you have administrator privileges.

To configure the approval process for ownership changes of assets

1. On the title bar, expand the menu options icon and select Administration.

2. Select General > Change owner/teams.

3. Set the Enable toggle button to the on position .

4. Select the team of approvers from the Approvers list.

5. Select Anyone in the Approved by list.
   This specifies that any user associated with the approvers’ access profile specified in the Approvers list can approve or reject the requests.

6. Select the Team approvers option to allow team approvers to approve the ownership change requests of assets that the team is associated with.
   You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
   If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

8. In the Configure approval initiate request mail template to be sent to the approver section, provide the following information:
   

   • Select Send notification to send an email notification to the approver for the pending approval.
   • Provide the text to display in the subject line and the body of the email.

   

   Note

   The at sign (@) character acts as a place holder and API Gateway automatically generates the values. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers’ login ID.

9. In the Configure request approved mail template to be sent to the requester section, provide the following information:

   • Select Send notification to send an email notification to the approval requester.

   • Provide the text to display in the subject line and the body of the email.

   

   Note

   The at sign (@) character acts as a place holder and API Gateway automatically generates the values. For example, Approval of @event.type appears as Approval of Change ownership in the email sent, where Change ownership is the event.type.

10. In the Configure rejection mail template to be sent to the requester section, provide the following information:

    • Select Send notification to send an approval rejection notification to the requester.

    • Provide the text to display in the subject line and the body of the email.

    

    Note

    The at sign (@) character acts as a place holder and API Gateway automatically generates the values. For example, Rejection of @event.type appears as Rejection of change of ownership of an asset in the email.

11. Click Save.

Approval Requests

You can manage your pending requests in the Pending Requests section. You can approve or reject a pending request or delete the requests approved by you.

The Pending Requests section displays the list of requests that you can approve. The following table lists the request types and the users who can view them:

To approve or reject a pending request

1. Expand the menu options icon , in the title bar, and select Pending Requests. The Pending requests page appears.

2. Select Pending Requests.
   A list of pending requests appears with the following information:

   Field	Description
   Requested by	The name of the requestor.
   Requestor comments	The additional information or comments added by the requestor.
   Event	The type of event for which the request is pending.
   Request details	The details of the type of event requested.

3. Click the Approve or Reject icon to approve or reject requests.
   Alternatively, you can select multiple pending requests to be approved or rejected simultaneously by selecting the check boxes adjacent to the names of the requests. The request gets removed from the Pending requests page.

Deleting Requests

When you perform a task, for example, you create an application in API Gateway, then an approval request is generated if an approval is configured in API Gateway and this request that is waiting for approvers approval is listed in the Pending Request section. If you want to delete this request, you can delete it from the Pending Request section.

To delete a request

1. Expand the menu options icon , in the title bar, and select Pending Requests.

2. Select My requests.
   A list of requests appears with the detailed information of the request.

3. Click the Delete icon for the request that has to be deleted.

4. Click Yes in the confirmation dialog.

URL Aliases

A URL alias is an alias that you create to replace a portion of the URL to an API on API Gateway. The URL alias typically replaces the path portion of the URL which identifies the name and invocation endpoint of the API. For example, if the URL is http://test:2225/gateway/RESTCalcService/1.0, you can create a URL alias, calc for an API, then the name and invocation endpoint of the API on API Gateway is replaced with calc, for example, http://test:2225/calc. If the client sends a request that contains the matching alias, then the corresponding URL path is invoked.

In addition to associating a URL alias with a single resource, you can also map different resources for each port, therefore, based on the incoming port, the corresponding resource path is invoked. This makes it possible to define a single URL alias that resolves to different destinations based on the incoming port of the HTTP request.

URL aliases have several benefits:

• A URL alias may be easier to type than full URL path names.

• A URL alias is more secure than URL path names.

The URL aliases page displays a list of available URL aliases with the corresponding details including the default URL path, port it is mapped to, and so on. You must have the Manage aliases functional privilege assigned to manage the alias information.

In the URL aliases page, with the Global gateway endpoint section, you can also define global gateway endpoint. For more information about global gateway endpoint, see How do I Define Global Gateway Endpoint?

API Gateway only supports modification of URL aliases for the WmAPIGateway package.

Creating URL Alias

When you create a URL alias, you create an association between an alias and an API on API Gateway.

Keep the following information in mind when creating a URL alias:

• An alias name must be unique across API Gateway.

• You can associate a single URL alias with multiple resources by specifying port mappings. A port mapping correlates the alias with a different URL alias based on the port on which th request was received.

• If you want to use URL alias with a REST resource you must enable partial matching of URL aliases.

• If you enabled or intend to enable partial matching of URL aliases, do not define an alias that begins with another alias.

To create a URL alias

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > URL aliases.
   This displays a list of available URL aliases and the corresponding details.

3. Click Add URL alias and provide the following information:

   Field	Description
   Alias	The alias name of the proxy server. An alias name must be unique across API Gateway. The alias name cannot include a space, nor can it include the following characters: # % ? ‘ “ < \ The alias name cannot begin with the string http:// or https://.
   Default URL path	The URL path to the API on API Gateway. You must specify the default URL path if you do not define any port mappings for the URL alias. If the URL alias includes port mappings, the Default URL Path field is optional. The URL path cannot include a space or the following characters: # % ? ’ “ < |

4. Click Save.

Enabling Partial Matching of URL Aliases

In some cases, URL requests include identifiers for a particular API. Because these identifiers vary for each instance of an API, URL requests might not exactly match any of the defined URL aliases for a particular API. To enable you to define URL aliases for such APIs, API Gateway can use partial matching to process URL requests. A partial match occurs when a request URL matches or begins with only part of a URL alias.

When partial matching is enabled and API Gateway receives a request URL, an alias is considered a match if the entire alias matches all or the beginning of the request URL, starting with the first character of the request URL’s path.

For example, if URL alias calc has a URL path of gateway/RESTCalcService/1.0 and API Gateway receives the following request URL:

https://MyHost:9072/calc/deleteCalc

The request URL matches the calc alias and resolves to the path: https://MyHost:9072/gateway/RESTCalcService/1.0/deleteCalc.

API Gateway retains the trailing characters of the request URL. In this case, API Gateway retains the /deleteCalc.

To enable API Gateway to use partial matching of URL requests, you must set the value of the parameter watt.server.url.alias.partialMatching to true in API Gateway, go to Administration > General > Extended settings. The default is false.

Modifying a URL Alias

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > URL aliases.

3. In the URL Alias list, select the URL alias that you want to edit.
   Alternatively, in the URL Alias list, locate the row that contains the alias you want to modify, and click the Edit icon.

4. Incorporate the required changes.

5. Click Save.

Deleting a URL Alias

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > URL aliases.

3. In the URL Alias list, locate the row that contains the alias you want to delete, and click .

4. Click Yes in the confirmation dialog box.

Example - Usage Scenarios of URL Aliases

This section explains how an API consumer can invoke an API for which a URL alias is created. In this example, we use the RESTCalcService API. Suppose, the RESTCalcService API is activated in API Gateway and following are the gateway endpoints for this API:

• http://test:2225/gateway/RESTCalcService/1.0

• http://test:4000/gateway/RESTCalcService/1.0

• http://test:4010/gateway/RESTCalcService/1.0

• http://test:5555/gateway/RESTCalcService/1.0

Also, the RESTCalcService consists of the postCalc resource path that adds two numbers.

If this API is published to the API consumer then the invocation endpoint for the consumer may appear as:

https://test:5555/gateway/RESTCalcService/1.0/postCalc

If you do not want to expose the API name and path information or if you want to shorten the invocation endpoint as it is complex, then you can create a custom URL alias. To create a URL alias:

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > URL aliases.

3. Click Add URL alias and provide the following values:

   Field	Value
   Alias	calc
   Default URL path	gateway/RESTCalcService/1.0/postCalc

4. Click Save.

   Suppose, the URL alias name provided while creating a URL alias is calc. You can now expose the https://test:5555/calc invocation endpoint to the API consumer instead of https://test:5555/gateway/RESTCalcService/1.0/postCalc.

   With the default URL path specified in alias configuration, the API consumer can use this URL alias for any ports of gateway endpoint shown in the API details page, for example,

• http://test:2225/calc

• http://test:4000/calc

• http://test:4010/calc

• http://test:5555/calc

Custom Content-types

An API Provider can configure custom content-types based on how the payloads in the incoming or outgoing requests have to be processed. If the native API consumes some custom content-type, the API Provider can configure a mapping between this custom content-type and a base content-type so that the schema validation, and identification in the policies are performed based on the base type.

For example, a native API consumes application/xyz content-type. The API provider creates an API for this native API and enforces the Validate API Specification policy and the API definition has schema mapping for application/json. When the request reaches API Gateway and as there is no content-type schema mapping for application/xyz, the schema validation is skipped. In such scenarios, if the API provider creates a custom content-type mapping in the API Gateway UI with the content type as application/xyz and base type as JSON, then the payload in the incoming request is validated against the JSON schema.

The following table explains the different identifiers and payload validation criteria that can be used for various content types that you can use to configure your custom content-types.

Configure Custom Content-types

When you configure a custom content-type, you specify what base-type the content type while processing the content.

You must have the API Gateway’s manage general administration configurations functional privilege assigned to configure custom content-type.

To configure custom content-type

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > Custom Content-types.

3. Provide the Content-type that has to be configured.

4. Select the Base type as one of the following:

   • JSON: Specifies that the base-type for the provided Content-type is set to JSON.

   • XML: Specifies that the base-type for the provided Content-type is set to XML.

   • Text: Specifies that the base-type for the provided Content-type is set to plain text.

5. Click .
   You can configure multiple custom content-types by clicking Add.

Configuring API Callback Processor Settings

You can configure the API callback processor setting All API callback requests so that API Gateway accepts all the requests from the client that contain the callback request URL and wrap the requests with its own URL before routing them to the native API. This lets API Gateway track the requests that the client sends to the native API and the callback messages that are sent by the native API to the client. In addition, you can use the settings Allow HTTPS access only and Process only allowed IPs requests to avoid any external threats in case an unauthorized user tries to access the protected resource.

You must have manage general administration configurations functional privileges to configure callback processor settings.

To configure API callback processor settings

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select General > Callback processor settings.

3. Select All API callback requests.
   This enables API Gateway to accept all the API callback requests coming from the client and wraps these requests with its own URL before it routes these requests to the native API. This option is selected by default.
   

   When this setting is disabled, the request from the client reaches the native API, as is, without the API Gateway wrapping it with it own URL. So, when the native API sends out the callback request to the client it directly reaches the client and API Gateway is unable to track such events.

4. Select Allow HTTPS access only.
   This allows API Gateway to receive only HTTPS callback requests from the native API and processes the requests before routing them to the client. If a HTTP callback request comes in, API Gateway sends out an Access denied message to the client. This option is selected by default.

   If this option is not selected then API Gateway accepts the HTTP callback requests and processes the requests before routing them to the client.

5. Select Process only allowed IPs requests.
   This allows API Gateway to receive the callback requests only from the IP addresses specified in the Trusted IP addresses list. API Gateway allows callback requests only from the allowed IPs configured in Trusted IP address list. You can configure your native APIs machine IPs or the native API outbound proxy server IPs here, so API Gateway allows a request coming from the native API and would then be routed to the client.

   If there are no trusted IPs configured and this option is selected, then API Gateway does not allow any requests.

6. Type the IP address in the Trusted IP address and Add.
   You can add multiple IP addresses. API Gateway allows only requests coming from these IP addresses when the option Process only allowed IPs requests is selected.

7. Click Save.

Destination Configuration

API Gateway can publish events and performance metrics data to the configured destinations. Event type data provides information about activities or conditions that occur on API Gateway. The performance data provides information on average response time, total request count, fault count, and so on, for the APIs that it hosts.

You must have the API Gateway’s manage destination configurations functional privilege assigned to configure the following destinations to which the event types and performance metrics data is published:

• API Gateway
• Developer Portal

• CentraSite

• API Control Plane

• Elasticsearch

• Email

• Custom destinations

Note:In addition to this list of destinations, you can configure custom destination to publish data to different components. For details on custom destinations, see Custom Destination.

Configuring Events for API Gateway Destination

You have to configure the API Gateway destination so that the events and performance metrics data can be published to API Gateway. By default, error events, lifecycle events, policy violation event, and performance data are published to API Gateway.

To configure events for API Gateway destination

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select Destinations.

3. Select API Gateway to configure the event types for this destination.

4. In Event types, select the type of events to publish to API Gateway.

   The available event types are:

   • Error: Occurs each time an API invocation results in an error.

   • Lifecycle: Occurs each time API Gateway is started or shut down.

   • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.

5. Select Report performance data to publish performance metrics data.

6. In the Publish interval box, enter a time interval (in minutes) how often API Gateway must publish performance metrics. Enter a value from 1 through 60. The default is 60 minutes.

7. In the Audit log data section, select the required management areas for which the audit logs should be recorded in the API Gateway destination.

   Audit logs provide a record of system transactions, events, and occurrences in API Gateway. You can configure audit logging to show the following events:

   • API management

   • Application management

   • Team management

   • Group management

   • Package management

   • Promotion management

   • Approval management

   • Alias management

   • Analytics management

   • Policy management

   • Plan management

   • User management

   Note: By default, audit logging is enabled for all of the above-listed management areas in the API Gateway destination.

8. Click Save.

Troubleshooting Tips: API Gateway Destination

I see that I am not able to parameterize custom indices for transaction events in API Gateway.

Custom indices can be configured for transaction events in API Gateway under Destinations > Elasticsearch > Configuration page. But parameterizing custom indices is not supported in API Gateway. For example, appending the current date to the index name. Consider an index name txnData and it must be appended with the current date, that is txnData_12_08_2020 and rolled up daily.

Resolution:

You can achieve this use case using the Elasticsearch aliases and rollover APIs of Elasticsearch.

A sample use case is as follows:

Create an alias in the Elasticsearch server, for example txnData and an index rollover like txnData_12_08_2020, txnData_12_08_2020. The alias txnData should point to all the indices txnData_12_08_2020, txnData_12_08_2020. One of the indices in the list is write-enabled and that are the latest and rest of the indices is read-only.

API Gateway sends the events to txnData alias and that alias defines the index that it should write the data to, based on the date.

Configuring Developer Portal Destination

You have to configure Developer Portal as a destination to establish communication channel between API Gateway and Developer Portal to exchange data.

To configure Developer Portal destination

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select Destinations.

3. Select Developer Portal > Configuration to configure Developer Portal as the destination.

4. Provide the following information in the Basic information section:

   Field	Description
   Name	Name of the Developer Portal being configured. The name should be unique as it is referenced in the list of providers within Developer Portal. This uniqueness is important when multiple API Gateways are publishing APIs to the same Developer Portal.
   Version	Version of the portal being configured.

5. Provide the following information in the Portal configuration section for Gateway to send data to Developer Portal:

   Field	Description
   Base URL	URL of the Developer Portal instance in the format http://hostname.
   Tenant	The tenant details of Developer Portal. By default, default tenant is considered if the tenant information is not provided.
   Username	Username credential to access Developer Portal instance.
   Password	Password credential to access Developer Portal instance.

6. Provide the following information in the Gateway configuration section for Developer Portal to create applications, request or revoke access tokens, subscriptions, and so on:

   Field	Description
   Base URL	URL of the API Gateway instance. This is pre-populated. Note: When a load balancer URL is updated in API Gateway, the API Gateway base URL is be updated to same in this field.
   Username	Username credential of the API Gateway Administrator to access API Gateway instance.
   Password	Password credential to access API Gateway instance.
   Stage name	Optional. The stage name of one of the stages in an API Gateway instance. The stage name included here is displayed in the API details, API tryout, Manage APIs, and Application details pages in the Developer Portal instance.

7. Click Test to ensure the connection with the Developer Portal details is established. This connection with the given server is tested and a success message appears.

8. Click Publish.
   This establishes a communication channel between API Gateway and Developer Portal.

Configuring Events for Developer Portal Destination

Pre-requisites:

You have to configure Developer Portal to communicate with API Gateway before you select the events and metrics for publishing to Developer Portal.

You have to configure the Developer Portal destination so that the events and performance metrics data can be published to Developer Portal.

To configure events for Developer Portal destination

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select Destinations.

3. Select Developer Portal > Events to configure the event types for this destination.

4. In Event types, select the type of events that you want API Gateway to publish to Developer Portal.

   The available event types are:

   • Error: Occurs each time an API invocation results in an error.

   • Lifecycle: Occurs each time API Gateway is started or shut down.

   • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.

5. Select Report performance data to publish performance metrics data.

6. In the Publish interval box, enter a time interval (in minutes) how often API Gateway must publish performance metrics. Enter a value from 1 through 60. The default is 60 minutes.

7. Click Save.

Post-requisites:

After performing the event configurations, select Developer Portal as a Destination in the Policy Properties page for each policy, to receive the transaction event logs for the assigned policies.

Configuring API Control Plane

API Control Plane is a centralized control and monitoring system that oversees and manages the entire API management landscape deployed across multiple regions, including cloud and on-premise environments. Connecting API Gateway to API Control Plane enables you to control and manage the performance of API Gateway effectively through API Control Plane.

To connect API Gateway to API Control Plane, it is essential to configure API Control Plane agent within API Gateway to establish a communication channel with API Control Plane. The agent is responsible for establishing and maintaining communication with API Control Plane.

You can configure API Control Plane agent through API Gateway UI. To configure the API Control Plane agent through the API Gateway UI, ensure you are using API Gateway version, 10.15.0 Fix 11 or later.

Pre-requisite:

You must have API Gateway’s manage destination configurations functional privilege assigned to configure API Control Plane.

To configure API Control Plane agent through API Gateway UI

1. Expand the menu options icon in the title bar, and select Administration.

2. Select Destinations.

3. Select API Control Plane > Configuration to configure API Control Plane agent.

4. Provide the following information in the API Gateway Basic information section:

   Field	Description
   Runtime name *	Name of the runtime (API Gateway instance). This field defines how you want to identify your API Gateway instance in API Control Plane. In the context of API Control Plane, a runtime refers to any product deployment within the API Management suite such as API Gateway, Developer Portal, and Microgateway.
   Description	Optional. Specify a description for the runtime.
   Tags	Optional. Tag of the runtime. Tags are used to categorize the runtimes. Example: test, local, dev. Note: A tag must not contain whitespaces.

5. Provide the following information in the API Gateway deployment section:

   Field	Description
   Deployment type	API Gateway deployment type. Default value: SAG_SAAS This field can not be edited.
   Region	Optional. Region name where API Gateway is deployed.
   Location	Optional. Country name where API Gateway is deployed.
   Host	Optional. Base URL of API Gateway in the format, http://hostname.
   Capacity	Optional. The approximate estimate of the throughput that API Gateway can handle for the specified duration. You can configure the capacity value with any non-negative integer.
   Capacity units	Optional. Choose the unit of duration in which the capacity must be defined. Possible values are as follows: per second per minute per hour per day per week per month per year

6. Provide the following information in the API Control Plane configuration section:

   Field	Description
   Control Plane URL *	Base URL of API Control Plane. Example: http://hostname
   Username *	Username that is used to log on to API Control Plane. Note: Ensure that the user belongs to API platform provider user group.
   Password *	Password of the corresponding user, which is used to log onto API Control Plane through basic authentication.

7. Provide the following information in the synchronization configuration section to synchronize the data from API Gateway to API Control Plane:

   Field	Description
   Metrics synchronization interval (in seconds)	The duration in seconds in which API Gateway must send its metrics data to API Control Plane. Default value: 120
   Asset synchronization interval (in seconds)	The duration in seconds in which API Gateway has to synchronize the changes made to the assets to API Control Plane. Default value: 180
   Retry max attempts	The maximum number of retry attempts allowed for API Gateway to establish a connection with API Control Plane if it is lost. Default value: 5
   Retry time interval (in seconds)	The duration in seconds in which API Gateway has to re-establish the connection with API Control Plane if it is lost. Default value: 60

8. Click Test to test the connection between API Gateway and API Control Plane.
   
   The connection with API Control Plane is tested and a success message appears.

9. Enable the API Control Plane communication toggle button to establish communication between API Gateway and API Control Plane.

10. Click Save.
    
    Agent configuration is saved in Elasticsearch and a communication is established between API Gateway and API Control Plane.

Note: When you re-configure and save the following configurations:

• Modifying runtime name field establishes a new communication channel, creating a new runtime in API Control Plane. The old runtime’s status turns red, indicating that the connection is lost.
• Modifying any field except the runtime name stops the existing communication channel and re-establishes with the updated values. During this period, the runtime’s status appears red, indicating that the connection is lost.
• If the connection is lost, the API Control Plane communication toggle button changes to a disabled state indicating that the connection is lost.

You can also manage API Control Plane agent configuration using REST APIs. For more details, see API Gateway Administration.

Configuring CentraSite Destination

You have to configure CentraSite as a destination to establish a communication channel between API Gateway and CentraSite to exchange data.

Once an API Gateway asset is published from CentraSite to API Gateway, the CentraSite communication and SNMP configuration details automatically appear in the CentraSite destination of API Gateway. If the same API Gateway asset is unpublished from the API Gateway instance at a later time, the CentraSite communication and SNMP configuration details are automatically removed from the CentraSite destination.

Note: If you have already configured CentraSite as a destination in API Gateway, then publishing another API Gateway asset from any CentraSite instance to API Gateway fails and displays an error. In API Gateway, only one CentraSite instance can be configured as a destination at a time. To reconfigure another CentraSite instance, you need to use the Force reset CentraSite communication and SNMP details option.

To configure CentraSite destination

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select Destinations.

3. Select CentraSite > Configuration to configure the CentraSite communication and SNMP details.

   The Communication section displays the following information:

   Field	Description
   Protocol	Specifies the communication protocol used to establish communication between API Gateway and CentraSite.
   Hostname	Specifies the host name or IP address of the machine on which CentraSite Application Server Tier (CAST) is running.
   UDDI port	Specifies the port on which CAST is listening. The default port number for CAST is 53307.
   Username	Specifies the CentraSite user ID for authenticating CentraSite when API Gateway communicates with CentraSite. This implies the user ID of a user who has the CentraSite Administrator role or the API Gateway Administrator role in CentraSite.
   Target name	Specifies the name of the API Gateway asset as defined in CentraSite.

   The SNMP section displays the following information:

   Field	Description
   Transport	Specifies the wire transport protocol that is used by the SNMP Listener. Supported values are: TCP and UDP.
   Hostname	Specifies the CentraSite host name or IP address to which the SNMP listener binds.
   Port	Specifies the port to which the SNMP listener binds. The default port number for CentraSite’s SNMP server is 8181.
   Username	Specifies the SecurityName that is used by the SNMP Listener.
   Authorization protocol	Specifies the authorization protocol that is used by the SNMP Listener for decoding the incoming trap. Supported values are: MD5 and SHA.
   Privacy protocol	Specifies the privacy protocol that is used by the SNMP Listener for decoding the incoming trap. Supported values are: DES, AES128, AES, AES192, AES256, 3DES, and DESEDE.

4. Select Send SNMP traps to CentraSite to publish data about the runtime events and metrics to the CentraSite SNMP server.

5. Select Force reset CentraSite communication and SNMP details, and click Reset to delete the current configuration and restore the system configuration.

6. Click Save. This establishes a communication channel between API Gateway and CentraSite.

Note: The transaction events are published from API Gateway to CentraSite using SNMP. The runtime metrics are published from API Gateway to CentraSite using a UDDI client.

Configuring Events for CentraSite Destination

Pre-requisites:

You have to configure CentraSite to communicate with API Gateway before you select the events for publishing to CentraSite.

You have to configure the CentraSite destination so that events and performance metrics data of APIs in API Gateway can be published to CentraSite. However, you will be able to publish the data to CentraSite destination only for APIs published from CentraSite to API Gateway.

To configure events for Centrasite destination

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select Destinations.

3. Select CentraSite > Events to configure the event types for this destination.

4. In Event types, select the type of events that you want API Gateway to publish to CentraSite.

   The available event types are:

   • Error: Occurs each time an API invocation results in an error.

   • Lifecycle: Occurs each time API Gateway is started or shut down.

   • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.

5. Select Report performance data to publish performance metrics data.

6. In the Publish interval box, enter a time interval (in minutes) to specify how often API Gateway must publish performance metrics. Enter a value from 1 through 60. The default is 60 minutes.

7. Click Save.

Post-requisites:

After performing the event configurations, select CentraSite as a Destination in the Policy Properties page for each policy, to publish the transaction and monitoring event logs for the assigned policies. API Gateway sends these events to CentraSite through SNMP.

Important: As a best practice, Software AG recommends you not to use the CentraSite destination for transaction events with large data payloads. This is because, the SNMP server using which the events are published from API Gateway to CentraSite does not handle transaction events with large data payloads.

Configuring Elasticsearch Destination

You have to configure Elasticsearch as a destination to establish a communication channel between API Gateway and Elasticsearch to exchange data.

To configure Elasticsearch destination

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select Destinations.

3. Select Elasticsearch > Configuration to configure Elasticsearch as the destination.

4. Provide the following information in the Basic information section:

   Field	Description
   Protocol	Specifies the communication protocol used to establish communication between API Gateway and Elasticsearch.
   Hostname	Specifies the host name or IP address of the machine on which Elasticsearch is running.
   Port	Specifies the port where Elasticsearch server runs. The default port number is 9240.
   Index name	Specifies the index name for Elasticsearch, where the data is stored.
   Username	Specifies the Elasticsearch user ID for authenticating Elasticsearch when API Gateway communicates with it.
   Password	Specifies the password of the Elasticsearch instance to be used for establishing communication between API Gateway and Elasticsearch.

   Note: You can provide the username and password for the Elasticsearch instances having configured with Basic authentication. You can also provide HTTPS enabled Elasticsearch instance.

5. Click Test.
   This tests the communication channel between API Gateway and the configured Elasticsearch.

6. Click Save to save the specified email configuration value.
   You can click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

Configuring Events for Elasticsearch Destination

Pre-requisites:

You have to configure Elasticsearch to communicate with API Gateway before you select Elasticsearch as a destination.

You have to configure Elasticsearch as a destination so that the event types and performance metrics data can be published to Elasticsearch.

To configure Elasticsearch destination

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select Destinations.

3. Select Elasticsearch > Events to configure the event types for this destination.

4. In Event types, select the type of events that you want API Gateway to publish to Elasticsearch.

   The available event types are:

   • Error: Occurs each time an API invocation results in an error.

   • Lifecycle: Occurs each time API Gateway is started or shut down.

   • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.

5. Select Report performance data to publish performance metrics data.

6. In the Publish interval box, enter a time interval (in minutes) to specify how often API Gateway must publish performance metrics. Enter a value from 1 through 60. The default is 60 minutes.

7. In the Audit log data section, select the required management area for which the audit logs should be recorded in the Elasticsearch destination.

   Audit logs provide a record of system transactions, events, and occurrences in API Gateway. You can configure audit logging to show the following events:

   • API management

   • Application management

   • Team management

   • Group management

   • Package management

   • Promotion management

   • Approval management

   • Alias management

   • Analytics management

   • Policy management

   • Plan management

   • User management

   Note: By default, audit logging is disabled for all of the above-listed management areas in the Elasticsearch destination.

8. Click Save.

Post-requisites:

After performing the event configurations, select Elasticsearch as a Destination in the Policy Properties page for each policy, to publish the transaction and monitoring event logs for the assigned policies.

Configuring Email Templates

API Gateway provides a default email template to send email alerts. You can compose and save the subject line as well as the email content for reuse. You can also customize the template to suit your needs.

To configure Email Templates

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select Destinations.

3. Select Email > Templates to configure the event templates.

4. Specify the following for the Log Invocation, Monitor SLA, Monitor Performance, and Traffic Optimization events:

   • Subject: The subject line of the email to be sent.

   • Content: By default, the template appears. You can customize the email content.

   The template consists of the following default information for the Log Invocation event:

   Note: The @ character is a place holder and the values are automatically generated by the system. For example, Status: @status appears as Status: SUCCESS in the email. You can use the existing parameters multiple times, delete the parameter if the parameter is not required from the available parameters, or use the corresponding optional parameters in the template. However, you cannot add new parameters.

   The transaction event parameters from the API Gateway Metrics and Event Notification engine are:

   Runtime_Policy: @policy_action_name
   API: @api_name
   Version : @version
   Operation or Resource_Name: @operation_resource_name
   Native endpoint: @native_endpoint
   Event generation time: @description
   Consumer_Name: @consumer_name
   Consumer_ID: @consumer_ID
   Status: @status
   Coorelation_ID:@correlationID
   Error origin: @errorOrigin
   

   The optional parameters that you can include in the template for the Log Invocation event are:

   Native payload : @nativeResponsePayload
   nativeRequestHeaders:@nativeRequestHeaders
   nativeRequestPayload:@nativeRequestPayload
   nativeResponseHeaders:@nativeResponseHeaders
   nativeResponsePayload:@nativeResponsePayload
   nativeHttpMethod:@nativeHttpMethod
   nativeURL:@nativeURL
   externalCalls:@externalCalls
   sourceGatewayNode:@sourceGatewayNode
   

   The template consists of the following default information for the Monitor SLA, Monitor Performance, and Traffic Optimization events:

   Note: You can use the existing parameters multiple times or delete the parameter if the parameter is not required from the available parameters in the template. However, you cannot add new parameters. The monitor event parameters from the API Gateway Metrics and Event Notification engine are:

   Runtime_Policy: @policy_action_name
   API: @api_name
   Version : @version
   Operation or Resource_Name: @operation_resource_name
   Native endpoint: @native_endpoint
   Action type: @actionType
   Attribute: @attribute
   Consumer_Name: @consumer_name
   Consumer_ID: @consumer_ID
   Alert Message: @alertMessage
   

   Additionally, you can click to abandon the changes and revert to the default template. You can click to review the changes before adding the changes to the email content and click Save.

Custom Destination

You can configure custom destinations to publish events, performance metrics, and audit logs to a required destination.

You can configure the following four types of destinations using the custom destinations feature:

• External endpoint - Use this type to configure an external REST endpoint URL as a destination.
• AWS Lambda - Use this type to configure an Amazon Web Services \(AWS\) Lambda function as a destination.

Why Custom Destination?

API Gateway provides a set of destinations to which you can publish events to various components. But sometimes customer might require the data to be published to a custom destination for further data processing and generating of various reports as per their business requirements. The custom destination feature offers solution to this requirement.

You can configure the custom destinations to publish either or all of the following:

You can use custom destination feature to perform:

Condition based publishing

You can configure conditions based on which API Gateway filters events to publish to a configured destination. That is, only the events that satisfy your conditions are published to the given destination. For example, you can configure a condition to publish the error events of the assets that satisfy your condition. Since this allows you to filter the data for an asset, you can achieve use cases like publishing of an API level policy violation events to a REST endpoint, publishing of the performance metrics data of an API to a messaging queue and so on.

To configure a condition, you can use variables available in the variable framework, and specify a matching value based on which the condition must be validated. You can specify multiple conditions and configure whether the data to be published must satisfy all or any of the given conditions. The use cases in this section explain the process of configuring conditions.

Steps to configure a custom destination

The following diagram outlines the steps involved in configuring a custom destination:

You can configure any number of custom destinations.

How Do I Publish Data to an External Endpoint using Custom Destination?

This use case explains how to publish data to a REST endpoint using custom destination.

The use case starts when you have data to be published and ends when you have successfully configured an REST endpoint URL as a destination to publish the data.

Ensure you have the external endpoint URL to which the data has to be published.

To publish data to an external endpoint

1. Expand the menu options icon , in the title bar, and select Administration.

2. Click Destinations.

3. Select Custom destinations from the left navigation pane.

4. Click + Add custom destination.

5. Provide the name of the custom destination in the Name field.

   The name must be unique and must not be the name of any pre-defined API Gateway destinations such as Elasticsearch.

6. To configure conditions that determine the data to be published in the specified destination, perform the following steps in the Conditions section:

   • Select one of the following options in the Condition type field:
   • And. To publish data that satisfies all your conditions.
   • Or. To publish data that satisfies one of your conditions.
   • Click + Add condition.

   • Provide the following details for your condition:

     • Variable. Name of the variable based on which you want to validate your condition. This field supports the variables that are available in the Variable framework. For details about the list of variables available, see Variable Framework.

     • Operator. The operator to use to relate variable and the value.

     • Value. The value of the variable that must be matched to satisfy the condition.

   

   • Click Add.
     

   The condition appears in the grid.

   Repeat this process to add the required number of conditions. Click on a condition to edit it and click next to a condition to delete it.

7. Select External endpoint in the Type field.

   

8. Provide the following information in the External Endpoint section, as required:

   Property	Description
   Endpoint URI	Provide the REST endpoint of the destination to publish the specified events. For example, http://localhost:9292/rest_endpoint/.
   Method	Specify the method exposed by the API. Available values are: GET, POST, PUT, DELETE, HEAD, and CUSTOM.
   SSL Configuration	Specifies the required SSL configuration details of the external endpoint. Provide the following information: Keystore Alias. Specifies the keystore alias. For details on Keystore configuration, see Keystore and Truststore. Key Alias. Specifies the alias for the private key, which must be stored in the keystore specified by the keystore alias. Truststore Alias. Specifies the alias for the truststore. For details on Truststore configuration, see Keystore and Truststore. HTTP Connection Timeout (seconds). Specifies the time interval (in seconds) after which a connection attempt to the external endpoint URL times out. Read Timeout (seconds). Specifies the time interval (in seconds) after which a socket read attempt times out.
   Path Parameters	Specifies the path parameter you want to configure to your custom extension. Provide the following information: Path Parameter Name. Specifies the name of the path parameter you want to configure in your custom extension. This path parameter name should be present in the endpoint URL enclosed with {} to be replaced at runtime. For example, define external URL as http://host/authors/{id}/books and provide id as path parameter name with the value you need to populate at runtime. Path Parameter Value. Specifies the value for the path parameter specified.

   

9. Configure the custom properties of the custom extension as required.

   For details about the custom extension properties and their descriptions, see Custom Extension Properties.

10. From the Events section, select the data that you want to publish to the configured destination. The options available are:

    • Event types. Type of events to publish to the specified destination. The available event types are:
    • Error: Occurs each time an API invocation results in an error.
    • Lifecycle: Occurs each time API Gateway is started or shut down.
    • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.
    • Performance metrics data. To publish to the specified destination.

    In the Publish interval of performance metrics data field, enter a time interval (in minutes) to specify how often API Gateway must publish performance metrics. Provide a value from 1 through 60. The default is 60 minutes.

    • Events. API Gateway modules for which the audit logs to publish to the specified destination.

11. Click Add.

    The custom destination is created successfully and appears in the Custom destinations page. The configured events are published in the specified destination.

    Note: To edit a custom destination, you can click the required custom destination, make changes and click Update. To delete a custom destination, click next to required custom destination. You cannot delete a custom destination that is associated with an API.

How Do I Publish API-specific Traffic Monitoring Data to a Custom Destination?

This use case explains how to publish traffic monitoring policy alerts to a custom destination of the external endpoint type.

The use case starts when you have data to be an API for which you configure traffic monitoring policy and ends when you have successfully selected a custom destination to publish the logs.

Ensure you have an API and a custom destination of the type external endpoint (with required REST Endpoint URL configured).

To publish traffic monitoring logs to a custom destination

1. Click APIs on the title navigation bar.

2. Click the required API.

   The API details page appears.

3. Click Edit.

4. Select Policies.

5. Click Traffic Monitoring and select a required policy.

6. Select the custom destination from the Destination section in the Policy Properties pane.

7. Select any other required details such as Alert interval, Unit, Alert frequency, Alert message and so on.

   

8. Click Save.

   The policy logs are published to the REST endpoint specified in the selected custom destination.

How Do I Publish Data to an AWS Lambda Function using Custom Destination?

This use case explains how to publish data to an AWS Lambda function.

The use case starts when you have data to be published and ends when you have successfully configured an AWS Lambda service as a destination to publish the data.

• Ensure you have an active Lambda function. For details on how to create an AWS Lambda function, see https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html
• Ensure you have configured AWS alias. For details on how to configure an AWS alias, see Configuring an AWS Alias.

To publish data to an AWS Lambda function

1. Click APIs on the title navigation bar.

2. Expand the menu options icon , in the title bar, and select Administration.

3. Click Destinations.

4. Select Custom destinations from the left navigation pane.

   The Custom destination page appears.

5. Provide the name of the custom destination in the Name field.

   The name must be unique and must not be the name of any pre-defined API Gateway destinations such as Elasticsearch.

6. To configure conditions that determine the data to be published in the specified destination, perform the following steps in the Conditions section:

   • Select one of the following options in the Condition type field:
   • And. To publish data that satisfies all your conditions.
   • Or. To publish data that satisfies one of your conditions.
   • Click + Add condition.

   • Provide the following details for your condition:

     • Variable. Name of the variable based on which you want to validate your condition. This field supports the variables that are available in the Variable framework. For details about the list of variables available, see Variable Framework.

     • Operator. The operator to use to relate variable and the value.

     • Value. The value of the variable that must be matched to satisfy the condition.

   • Click Add.

   The condition appears in the grid.

   Repeat this process to add the required number of conditions. Click on a condition to edit it and click next to a condition to delete it.

7. Select AWS Lambda in the Type field.

   

8. Provide the following information in the AWS Lambda section, as required:

   Property	Description
   Function Name	Provide the AWS Lambda function name to which you want to publish the configured data.
   Invocation Type	Specify the AWS invocation type, asynchronous or synchronous. Available options are: RequestResponse (synchronous type) Event (asynchronous type)
   AWS Alias	Provide the AWS alias configured for the AWS account.

   

9. Configure the custom properties of the custom extension as required.

   For details about the custom extension properties and their descriptions, see Custom Extension Properties.

10. From the Events section, select the data that you want to publish to the configured destination. The options available are:

    • Event types. Type of events to publish to the specified destination. The available event types are:
    • Error: Occurs each time an API invocation results in an error.
    • Lifecycle: Occurs each time API Gateway is started or shut down.
    • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.
    • Performance metrics data. To publish to the specified destination.

    In the Publish interval of performance metrics data field, enter a time interval (in minutes) to specify how often API Gateway must publish performance metrics. Provide a value from 1 through 60. The default is 60 minutes.

    • Events. API Gateway modules for which the audit logs to publish to the specified destination.

11. Click Add.

    The custom destination is created successfully and appears in the Custom destinations page. The configured events are published in the specified destination.

    Note: To edit a custom destination, you can click the required custom destination, make changes and click Update. To delete a custom destination, click next to required custom destination. You cannot delete a custom destination that is associated with an API.

Troubleshooting Tips: API Gateway - Developer Portal Integration

I see an obsolete Developer Portal destination reference in a published API.

An old Developer Portal destination reference is associated to all APIs. This old reference is not available anymore, however, it is still associated to all APIs. Hence, all APIs have two associated Developer Portal destinations, one correct and the other obsolete.

Remove the obsolete reference as follows:

1.Retrieve API details using the following GET REST call:
http://localhost:5555/rest/apigateway/apis/apiId

2.Retrieve associated portal information using the following GET REST call:
http://localhost:5555/rest/apigateway/portalGateways

3.Retrieve the API Gateway to Developer Portal association using the following GET REST call:
http://localhost:9240/gateway_default/deploymentmap/_search

For every API, this displays two entries; one for the actual portal reference and another for the stale reference. You can delete the stale reference documents from the datastore.

You can delete the stale reference by using the REST request as follows:

DELETE http://localhost:9240/gateway_default/deploymentmap/id

The id you provide here is the id corresponding to the stale reference details you see in the response for Step 3.


I cannot publish an API to Developer Portal.

If publishing APIs to Developer Portal fails, it might due to incorrect destination configuration for Developer Portal.

Resolution: Go to User menu > Administration > Destinations > Developer Portal. Ensure that all the required destination configuration details are provided correctly. If you make any changes you must republish the configuration for the changes to take effect.



I see stale applications in Developer Portal.

When a consumer subscribes to a plan or a package, an application is created both in API Gateway and Developer Portal. By mistake, when you delete an application from Gateway, the application in Developer Portal becomes stale.

To remove the stale applications from Developer Portal, unpublish the package associated with the application and republish it. This triggers the cleanup of the stale application in Developer Portal.

Audit Logging

The audit logging feature of API Gateway provides audit information for different categories of system transactions, events, and occurrences of specific events (for example, login attempts) over a period of time. You can use audit logs to view a detailed record of various auditable events that occurred on the API Gateway objects, user login and logout operations, and identify the users who are responsible for the changes. You can configure which audit events to log for a specific destination based on your auditing requirements.

You can configure API Gateway to log the auditable events for following destinations:

• API Gateway

• Elasticsearch

The following auditable events can be configured to write to the API Gateway audit logs:

• Access profile management events
  Access profile management consists of the following events:

  • Creation, modification, and deletion of an Access profile object.
    
    

• Alias management events
  Alias management consists of the following events:

  • Creation, modification, and deletion of an Alias object.
    
    

• Analytics management events
  Analytics management consists of the following events:

  • Archiving, purging, and restoring of analytics data in the database.
    
    

• API management events
  API management consists of the following events:

  • Creation, modification, and deletion of an API object.
    
  • Activation and deactivation of an API.
    
    

• Application management events
  Application management consists of the following events:

  • Creation, modification, and deletion of an Application object.
    
    

• Approval management events
  Approval management consists of the following events:

  • Approval and rejection of a request to create, register, and modify an application.
  • Approval and rejection of a request to subscribe a package in Developer Portal.
    
    

• Group management events
  Group management consists of the following events:

  • Creation, modification, and deletion of a Group object.
    
    

• Package management events
  Package management consists of the following events:

  • Creation, modification, and deletion of a Package object.
    
    

• Plan management events
  Plan management consists of the following events:

  • Creation, modification, and deletion of a Plan object.
    
    

• Policy management
  Policy management consists of the following events:

  • Creation, modification, and deletion of a global Policy object.
  • Creation, modification, and deletion of an API level Policy object.
  • Activation and deactivation of a global policy.
  • Activation and deactivation of an API level policy.
    
    

• Promotion management events
  Promotion management consists of the following events:

  • Creation, modification, and deletion of a Stage object.
  • Promotion of an API stage.
  • Rollback operation of an API stage.
    
    

• User management events
  User management consists of the following events:

  • A user logs in or fails to log in to API Gateway.
  • A user logs out of API Gateway.
  • Creation, modification, and deletion of a User object.
    
    

API Gateway writes the audit logging data to the Audit logs dashboard (in the API Gateway user interface, go to Analytics > Audit logs). You can view and download audit logs.

Best Practices for API Gateway Audit Logging

API Gateway’s audit logging feature has been implemented on an event-driven approach. By default, the API Gateway destination is enabled to log the auditable events for all areas of management, such as APIs, policies, users, and so on. As a best practice, Software AG recommends that you enable audit logging for the required management areas in other supported destinations: Database, Digital Events, and Elasticsearch. This practice is especially important when you want to provide the audit log data to external sources for analytics and anomaly detections.

Configuring Audit Logs

You have to configure which events you need to audit for a destination so that API Gateway logs the auditable events data to the specific destination. You can configure API Gateway to log the auditable events data to the following destinations:

• API Gateway

• Elasticsearch

• Custom Destination

The following events are available for audit log reports:

• Access profile management

• Alias management

• Analytics management

• API management

• Application management

• Approval management

• Group management

• Package management

• Plan management

• Policy management

• Promotion management

• User management

By default, all the auditable events are logged into the API Gateway destination.

To configure audit logs

1. Expand the menu options icon , in the title bar, and select Administration.

2. Select Destinations.

3. Select the required destination to log the auditable events.

4. In the Audit log data section, select the required management areas to monitor, audit, and report the data.

5. Click Save.

Viewing Audit Logs

You can use the audit log reports to view the data of auditable events.

To view audit logs

1. Expand the menu options icon , in the title bar, and select Analytics.
   The dashboard displays the API Gateway-wide analytics based on the metrics monitored.

2. Select Audit logs.

3. In the drop-down list, choose the time interval in which you want to view the data of auditable events. The available options are:

   • Last 2 days

   • Last 7 days

   • Last 30 days

   • Last 60 days

   • Last 90 days

   • Custom

4. If you select Custom, type the From Date and To Date to specify the time interval that best suits your needs.

5. Click Apply filter to filter the analytics based on the time interval chosen.
   You can view logs for API Gateway auditable events in the Audit logs dashboard. You can also download the API Gateway audit log in a text file and view the auditable events data.

Filtering Audit Log Results

In general, the number of audit logs displayed as a result of Audit log filter is large. Hence, you can refine the results using the following steps to view the required records.

You can filter the audit log results based on filters such creation date, event type, payload, and so on. For example, you filter audit logs for the last 90 days, and the number of audit logs for the filter is large, you can filter the log records for a given creation date, event type, or payload.

To filter audit logs

1. Click + Add filter above the audit logs grid.
   Logs that are filtered based on the given criteria appears.

2. Provide the following:

   • Field - Field based on which the records must be filtered.

   • Operator - Conditional operator applied for the filters.

   • Value - Search keywords for the given filters.

3. Click Save. Audit logs that match your filter criteria appear.

Downloading Audit Logs

You can download the audit log reports to examine the data of auditable events.

To download audit logs

1. Expand the menu options icon in the title bar, and select Analytics. The dashboard displays the API Gateway-wide analytics based on the metrics monitored.

2. Select Audit logs.

3. In the drop-down list, choose the time interval in which you want to view the data of auditable events.

4. If you select Custom, type the From Date and To Date to specify the time interval that best suits your needs.

5. Click Download to download and view the detailed report.
   API Gateway generates a compressed file of the audit logs and downloads it to the default download folder configured in your browser.

   The compressed file is named auditlogs_N.zip. The compressed file contains one or more simple text files, where each text file contains 10,000 audit log records.

   API Gateway audit log are listed below.

   Column	Detail
   id	Unique identifier of the event that produced the audit record.
   eventType	Type of event (audit log) that produced the record.
   creationDate	Date and time the event entry was written to the log.
   objectType	Type of object (for example, User, API, Application, and so on) on which the event occurred.
   action	Type of action (for example, Create, Update, Delete, and so on) that was performed on the object.
   object	Unique identifier of the API Gateway object on which the action was performed.
   message	Message that describes the event that occurred.
   user	Name of a user on the API Gateway instance that triggered the event.
   sourceMachine	The host name of the machine on which the API Gateway instance is running.
   clientIPAddress	IP address of the machine on which the API Gateway instance is running.
   payload	The request payload defined for the event.
   status	Current status of the event (Success or Failure).

Configuring External Accounts

API Gateway provides capability to add and configure service registries and communicate these changes across nodes in the cluster. An API Gateway administrator can add and remove service registries.

Service Registry

A service registry is essentially a catalog of services. Applications that expose services can register their services with one or more service registries. Applications that need to consume a service look up a service registry and obtain the address of an application server that provides the service. Using service registries with API Gateway adds resilience, scalability, and security to the application stack.

API Gateway uses service registries in the following ways:

• You can publish APIs defined in API Gateway to service registries. This enables other applications to use the service registry to dynamically locate an API Gateway instance that provides that API.

• You can set an API Gateway route to a service registry endpoint. This enables API Gateway to use the service registry to dynamically locate an application instance and route the request to it.

Service Registries supported by API Gateway

API Gateway currently supports the following service registries:

• Eureka: Eureka is a REST-based service for locating services for the purpose of load balancing and failover of middle-tier servers. It has been primarily designed for applications in the AWS cloud.

• Service Consul: Service Consul is a tool for discovering and configuring services in IT infrastructure.

Adding a Service Registry

You must have the Manage service registries functional privilege assigned to perform this task.

You have to add and configure a service registry in API Gateway before you reference it in an API. In cluster deployments of API Gateway, you can add a service registry on any API Gateway instance—other API Gateway instances are synced automatically.

To add and configure a service registry

1. Expand the menu options icon , in the title bar, and select Administration.

2. Click External accounts.

3. Click Add service registry.

   Field	Description
   Name	Name used by API Gateway for the instance of service registry that you are adding.
   Description	Description of the instance of service registry.
   Type	Type of service registry. Available values are: SERVICE_CONSUL and EUREKA.
   Endpoint configuration
   Endpoint URI	The base URI for the service registry. This should include the IP address or the FQDN and the port on which the service registry accepts requests.
   Service discovery path	The relative path of the service registry discovery service. API Gateway appends this path (and the service ID) to the Endpoint URI to generate a service discovery request for the service registry. Note: A service registry discovery service returns the address (IP address or FQDN) of an application instance for the requested service ID.
   Service registration path	The relative path of the service registry registration service. API Gateway appends this path (and the service ID) to the Endpoint URI to generate a service registration request for the service registry. Note: API Gateway uses this service to register (publish) a service with the service registry.
   Service de-registration path	The relative path of the service registry de-registration service. API Gateway appends this path (and the service ID) to the Endpoint URI to generate a service de-registration request for the service registry. Note: API Gateway uses this service to de-register (unpublish) a service with the service registry.
   Connection timeout (seconds)	Specifies the time (in seconds) after which a connection attempt times out while communicating with the service registry. The precedence of the Connection Timeout configuration is as follows: If you specify a value for the Connection timeout field in routing endpoint alias, then the Connection timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level. If you specify a value 0 for the Connection timeout field in routing endpoint alias, then API Gateway uses the value specified in the Connection timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration. If you specify a value 0 or do not specify a value for the Connection timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.connectionTimeout property. If you do not specify any value for pg.endpoint.connectionTimeout, then API Gateway uses the default value of 30 seconds.
   Read timeout (seconds)	Specifies the time (in seconds) after which a socket read attempt times out while communicating with the service registry. The precedence of the Read Timeout configuration is as follows: If you specify a value for the Read timeout field in routing endpoint alias, then the Read timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level. If you specify a value 0 for the Read timeout field in routing endpoint alias, then API Gateway uses the value specified in the Read Timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration. If you specify a value 0 or do not specify a value for the Read timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.readTimeout property. If you do not specify any value for pg.endpoint.readTimeout, then API Gateway uses the default value of 30 seconds.
   SSL configuration
   Keystore alias	List of keystores that are configured in API Gateway. This is used when the service registry is SSL enabled. Lists all available keystores.
   Key alias	Lists all the private keys that are present in the selected keystore alias. This is used when the service registry is SSL enabled.
   Truststore alias	A truststore contains the certificates that are trusted by API Gateway. If the service registry is SSL enabled its certificate should be added to the selected truststore.
   Basic authentication details
   Username	The basic authentication user name.
   Password	The basic authentication password.
   Other configuration
   Heartbeat interval	(This setting is applicable only to Eureka service registries.) The interval at which the API Gateway sends a heartbeat message to the Eureka server to renew its leases. Eureka expects clients, such as API Gateway, to renew the lease by sending heartbeats as per the heartbeat interval configured in the Eureka server.
   Headers
   Key	An HTTP header key that is included in all the HTTP requests sent to the service registry.
   Value	A value for the given HTTP header key.

4. Click Add. The service registry is added to API Gateway.

Removing a Service Registry

• You cannot remove a service registry if any API has been published to it.

• You can remove only the non-default service registries that are not used by any API.

• You must have the Manage service registries functional privilege assigned to perform this task.

In cluster deployments of API Gateway, you can remove the service registry on any API Gateway instance—other API Gateway instances are synced automatically.

To remove a service registry

1. Expand the menu options icon , in the title bar, and select Administration.

2. Click Service Registries.

3. Click in the row that has the service registry that you want to remove.

4. Click Yes to confirm.
   The service registry is removed from API Gateway.

Configuring an AWS Alias

Configure an AWS alias if you are using a custom extension that calls an AWS Lamdba function from within a runtime policy enforcement flow of API Gateway API.

To configure an AWS alias

1. On the title bar, expand the menu options icon and select Administration.

2. Click External accounts > AWS configuration.

3. Click Add new AWS account.

4. In the Add AWS configuration section, provide the following information:

   a. Name: Provide the AWS alias name.

   b. Description: Optional. Provide a description for the alias.

   c. Region: Provide the AWS account region where the Lambda function is running or deployed. For details on how to create an AWS Lambda function, see https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html.

   d. Access key ID: Provide the access key ID of the AWS account where the Lambda function is running.

   e. Secret access key: Provide the secret access key of the AWS account where the Lambda function is running.

5. Click Add. This creates the AWS alias and lists in the AWS configuration page.

Configuring Integration Server Instance for API Implementation

To implement an API to Integration Server, you must provide the details of the Integration Server instance(s) in API Gateway.

To configure an Integration Server details

1. Expand the menu options icon , in the title bar, and select Administration.

2. Click External accounts.

3. Click Integration servers. The list of configured Integration server instances appears.

4. Click Add new Integration servers. The options to add new Integration Server details appear.

5. Provide the following details:
   

   Field	Description
   Name	Name for the Integration Server instance being added.
   Description	Description for the configuration.
   Integration Server URL	URL of the Integration Server.
   User name	User credentials required to access the Integration Server instance.
   Password	Password required to access the Integration Server instance.
   Keystore alias	The text identifier for the Integration Server keystore file. The keystore contains the private keys and certificates (including the associated public keys) of Integration Server.
   Key alias	The The alias for a specific key in the specified keystore.

   

6. To validate the connectivity of the specified Integration Server instance, click Test. The connection with the given server is tested and a success message appears.

7. Click Add. The server details are saved.

Runtime Events and Metrics Data Model

API Gateway generates runtime events and Key Performance Indicator (KPI) metrics for the currently active APIs. The types of runtime events that API Gateway can generate are:

KPI metrics are used to monitor the run-time execution of APIs. Metrics include the maximum response time, average response time, fault count, availability of APIs, and so on. If you include runtime monitoring policies, the policies will monitor the KPI metrics for APIs, and can send alerts to various destinations when user-specified performance conditions for an API are violated. The KPI metrics that API Gateway can generate are:

You can configure API Gateway to publish the runtime events and metrics data to different destinations. The following sections describe the runtime events and metrics data model for each of these destinations:

• API Gateway
• Developer Portal

• Audit Log

• CentraSite

• Elasticsearch

• Email

• Local Log

API Gateway

The runtime events and metrics payload is generated by API Gateway at run-time. The columns that make up the events and metrics data model for API Gateway are listed below:

Transactional Events

Error Events

Monitoring Events

Lifecycle Events

Policy Violation Events

Performance Metrics

Threat Protection Events

Developer Portal

The runtime events and metrics payload generated by API Gateway at run-time is published to the configured Developer Portal destination. The columns that make up the events and metrics data model for Developer Portal are listed below:

Transactional Events

Error Events

Monitoring Events

Lifecycle Events

Policy Violation Events

Performance Metrics

Audit Log

The runtime events and metrics payload generated by API Gateway at run-time is published to the configured Audit Log destination. The columns that make up the events and metrics data model for Audit Log are listed below:

Transactional Events

CentraSite

The runtime events and metrics payload generated by API Gateway at run-time is published to the configured CentraSite destination. The columns that make up the events and metrics data model for CentraSite are listed below:

Transactional Events

Error Events

Monitoring Events

Policy Violation Events

Lifecycle Events

Performance Metrics

Elasticsearch

The runtime events and metrics payload generated by API Gateway at run-time is published to the configured Elasticsearch destination. The columns that make up the events and metrics data model for Elasticsearch are listed below:

Transactional Events

Error Events