Usage Scenarios

Change Ownership of Assets

Assets such as APIs and applications in API Gateway have an option where the ownership of the asset can be changed. Applications have confidential data like API key and client certificates which only the owner can view. Therefore, if the owner of an asset has to take up a different responsibility or leave the organization, no other user can view the secrets of the asset. The edit option available on the asset details page, enables the transfer of ownership of the asset to another user, so that the new owner of the asset can access or view the confidential data of the asset. API Gateway provides an option to configure an approval process for the assets’ ownership change. Approval and auditing contribute to the governance of change ownership.

Before you begin

Ensure that you have:

For details on functional privileges available, see API Gateway Functional Privileges.

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?

The figure depicts the workflow for changing ownership of assets:

How Do I Change the Ownership of an Application?

This use case explains how to change the ownership of an application. You can configure an approval process for the change of ownership to take effect, if required.

The use case starts when an application requires a change of owner and ends when you successfully change the application’s ownership.

In this example, an application app1 is owned by user1. The ownership of app1 has to be changed to user2 through an approval process.

Before you begin

Ensure that you have the change owner privilege.

To change the ownership of an application

  1. Log on to API Gateway as a user with the change owner privilege.

  2. Click Applications on the title navigation bar.

  3. Click the required application app1. The application details page appears. The owner of the application app1 is user1 as displayed in the Basic information section.

  4. Click .

  5. Select user2 from the list and click .

    The change approval process is initiated.

    Note: If the approval flow is not configured, the owner of the application changes to user2 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 ownership of app1 remains with user1.

  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.

  9. The owner of the application app1 is changed from user1 to user2.

How Do I Change the Ownership of an API?

This use case explains how to change the ownership of an API. You can configure an approval process for the change of ownership to take effect, if required.

The use case starts when you have an API that requires a change of owner and ends when you successfully change the API’s ownership.

In this example, an API petstore is owned by user1. The ownership of petstore has to be changed to user2 through an approval process.

Before you begin

Ensure that you have the change owner privilege.

To change the ownership of an API

  1. Log on to API Gateway as a user with the change owner privilege.

  2. Click APIs on the title navigation bar.

  3. Click petstore.

    The API details page appears. The owner of the API petstore is user1 as displayed in the Basic information section.

  4. Click change.

  5. Select user2 from the list and click .

    The change approval process is initiated.

    Note: If the approval flow is not configured, the owner of the API changes to user2 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 ownership of petstore remains with user1.

  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.

  9. The owner of the API petstore is changed from user1 to user2.

How Do I Change the Ownership of Multiple Assets?

It is convenient to change the asset ownership for multiple assets with a single REST request than doing it separately for individual assets. This use case explains how to change the ownership of multiple assets 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 assets require change of owner and ends when you successfully change the ownership of the assets to another user.

To change the ownership of multiple assets

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

    POST http://host:port/rest/apigateway/assets/owner
    	
    
    Content-Type: application/json
    	
    
    {
    	"assetType": "*", (API/APPLICATION)
    	"assetIds": ["*"],
    	"currentOwner": "user1",
    	"newOwner": "user2"
    	
    
    }

    Provide the following information in the REST request:

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

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

      Note: This is optional. assetIds is not required if you specify currentOwner.

    • currentOwner. Specifies the user name of the owner of the assets specified in the assetType field.

      Note: If both currentOwner 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 currentOwner field, then only assetID1 ownership changes.

    • newOwner. Specifies the user name of the user who would be the new owner of the assets specified.

    Example 1: If user1 owns two assets, an API petstore and application app1, and you want the ownership to be transferred to user2, send a REST request as follows:

    POST http://localhost:5555/rest/apigateway/assets/owner
    	
    
    Content-Type: application/json
    	
    
    {
    	"assetType": "*", (API/APPLICATION)
    	"currentOwner": "user1",
    	"newOwner": "user2"
    }

    This request transfers the ownership of all the assets owned by user1 to user2.

    The change approval process is initiated.

    Example 2: user1 owns three APIs, api1, api2, and api3 and two applications, app1 and app2. If you want the ownership of api1, api2, and app1 to be transferred to user2, send a REST request as follows:

    POST http://localhost:5555/rest/apigateway/assets/owner
    	
    
    Content-Type: application/json
    	
    
    {
    	"assetType": "*", (API/APPLICATION)
    	"assetIds": ["apiID1, apiID2, appID1"],
    	"currentOwner": "user1",
    	"newOwner": "user2"
    }

    where apiID1, apiID2, and appID1 are asset IDs of api1, api2, and app1 respectively.

    The change approval process is initiated.

    Note: If the approval flow is not configured, the ownership of the assets changes from user1 to user2. Skip to step 4.

  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. The owner of the assets is changed from user1 to user2.

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. 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.

  7. 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.

  8. 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.

  9. Click Save.

Custom Policy Extension

API Gateway provides a range of out-of-the-box policies to address common API management requirements like security, transformation, validation, error processing, and so on. In addition, API Gateway provides an option to add custom extensions or custom variables.

Custom Extensions

You can add these custom extensions into API Gateway policy stages to handle a requirement that might not be handled by any of the existing policies. You can use custom extensions in conjunction with the existing policies across stages. For example, if you want to invoke a third-party API or call an external endpoint during any stage of API processing, you can add custom logic in the corresponding policy stage and use it as required.

API Gateway supports the following custom extension types:

Custom extensions are applicable to the REST, SOAP and OData API types. Custom extensions are supported at all levels such as, API, Scope, Global and can be added in any or all policy enforcement stages except the transport policy and the traffic monitoring policy stages.

The figure depicts a sample workflow for custom extension support in the request and response processing stages in API Gateway:

Custom Variables

You can configure custom variables under custom extension policy. You can assign a value or a variable expression to a custom variable which can be used in other policy parameters. Custom variable also provides option to set custom field to the transactional events. To set the custom fields, you have to define customTransactionFields.FIELD_NAME custom variable. It also provides an option to configure namespaces for Xpath expressions. To configure the namespaces you have to define XpathNamespaces custom variable.

How Do I Invoke a Service through HTTP/HTTPS using Custom Extension?

This use case explains how to invoke a service through HTTP/HTTPS using custom extension. The custom extension configured can be enforced in any of the policy stages and used during API processing.

The use case starts when you have an API that has to be enforced with a custom extension and ends when you successfully invoke the API with the custom extension enforced.

To invoke a service through HTTP/HTTPS using custom extension

  1. Ensure you have the external endpoint URL to be invoked during API processing using a custom extension.

  2. Click APIs on the title navigation bar.

  3. Click the required API.
    The API details page appears.

  4. Click Edit.

  5. Select Policies.

  6. Click Required Policy stage > Custom Extension.
    This adds the custom extension policy where you can configure the required properties.

  7. Click to open the policy properties section in a full page.

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

    Parameter Description
    Condition Conditions are used to specify when the policy has to be executed. We can add multiple conditions with logical operators. .

    Available values are:

    • AND. API Gateway executes this policy when all the configured conditions comply in the respective policy stage.
    • OR. This is selected by default. API Gateway executes this policy when any one of the configured conditions complies.
    • Click Add Condition and provide the following information and click icon.

    • Variable. Specifies the variable type with a syntax.
    • Operator. Specifies the operator to use to relate variable and the value. You can select one of the following:
      • Equal
      • Equals ignore case
      • Not equals
      • Not equals ignore case
      • Contains
      • Exists
      • Greater Than
      • Less Than
    • Value. Specifies a plain value or value with a syntax.

    For details about the variables available in API Gateway, see Variables Available in API Gateway.

  9. Click Custom Action.

  10. Select External endpoint in the custom extension Type field.

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

    Property Description
    Endpoint URI Provide the external endpoint URI that you want to invoke.
    Method Specify the method exposed by the API. Available values are: PUT, POST, GET, DELETE, HEAD, CUSTOM.

    Note: If you select CUSTOM, the HTTP method in the incoming request is sent to the native API.
    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. Species 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.
  12. Configure the custom properties of the custom extension as required.
    For details about the custom extension properties and their descriptions, see Custom Extension Properties.

  13. Click Save.
    The API is saved with the added custom extension.

  14. Invoke the API.
    The applied custom extension invokes the mentioned HTTP/HTTPS endpoint and processes as configured.

How Do I Invoke an AWS Lambda Function using Custom Extension?

This use case explains how to invoke an AWS Lambda function using custom extension. The custom extension configured can be enforced in any of the policy stages and used during API processing.

The use case starts when you have an API that has to be enforced with a custom extension and ends when you successfully invoke the API with the custom extension enforced.

To invoke an AWS Lambda function using custom extension

  1. Create a Lambda function and ensure it is active.
    For details on how to create an AWS Lambda function, see https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html.

  2. Configure AWS alias.
    For details on how to configure an AWS alias, see Configuring an AWS Alias.

  3. Click APIs on the title navigation bar.

  4. Click the required API.
    The API details page appears.

  5. Click Edit.

  6. Select Policies.

  7. Click Required Policy stage > Custom Extension.
    This adds the custom extension policy where you can configure the required properties.

  8. Click to open the policy properties section in a full page.

  9. Provide the following information in the Conditions section, as required:

    Parameter Description
    Condition Conditions are used to specify when the policy has to be executed. We can add multiple conditions with logical operators. .

    Available values are:

    • AND. API Gateway executes this policy when all the configured conditions comply in the respective policy stage.
    • OR. This is selected by default. API Gateway executes this policy when any one of the configured conditions complies.
    • Click Add Condition and provide the following information and click icon.

    • Variable. Specifies the variable type with a syntax.
    • Operator. Specifies the operator to use to relate variable and the value. You can select one of the following:
      • Equal
      • Equals ignore case
      • Not equals
      • Not equals ignore case
      • Contains
      • Exists
      • Greater Than
      • Less Than
    • Value. Specifies a plain value or value with a syntax.

    For details about the variables available in API Gateway, see Variables Available in API Gateway.

  10. Click Custom Action.

  11. Select AWS Lambda in the custom extension Type field.

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

    Property Description
    Function Name Provide the AWS Lambda function name you want to invoke. As this property supports variable framework, you can use the available Function Name variables. For details about the variables available in API Gateway, see Variables Available in API Gateway.
    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.
    Client Configuration Provide the following client configuration details and click .

    • Name. Start typing the client property name and select the required property from the type-ahead search results displayed.

      API Gateway supports the following properties that you can configure: Socket timeout(ms), Connection timeout(ms), Request timeout(ms), Connection expiration timeout(ms), Maximum Coneection idle time(ms), Client execution timeout(ms), Server error retry count, Enable throttle retries, Maximum client retry count, TCP send buffer size hints, TCP receive buffer size hints, Enable gzip requests, Enable Expect-Continue, Enable host prefix injection, Enable Keep-alive, Enable, Response metadata caching, Response metadata cache size, and Signature Algorithm.

    • Value. Provide a value for the client property specified. You can configure multiple properties.

      For details about the supported client properties, see the following AWS documents:

  13. Configure the custom properties of the custom extension as required.
    For details about the custom extension properties and their descriptions, see Custom Extension Properties.

  14. Click Save.
    The API is saved with the added custom extension.

  15. Invoke the API.
    The applied custom extension invokes the AWS lambda function and processes as configured.

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.

How Do I Define a Custom Variable?

This use case explains how to define custom variable using custom extension. The defined custom variable can be used in any of the subsequent policy stages during API processing.

The use case starts when you have to define a custom variable, which is not available in API Gateway and ends when you successfully defined and accessed the variable in the subsequent policy stages.

To define a custom variable using custom extension

  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 Required Policy stage > Custom Extension.
    This adds the custom extension policy where you can configure the required properties.

  6. Click to open the policy properties section in a full page.

  7. Provide the following information in the Conditions section, as required:

    Parameter Description
    Condition Conditions are used to specify when the policy has to be executed. We can add multiple conditions with logical operators. .

    Available values are:

    • AND. API Gateway executes this policy when all the configured conditions comply in the respective policy stage.
    • OR. This is selected by default. API Gateway executes this policy when any one of the configured conditions complies.
    • Click Add Condition and provide the following information and click icon.

    • Variable. Specifies the variable type with a syntax.
    • Operator. Specifies the operator to use to relate variable and the value. You can select one of the following:
      • Equal
      • Equals ignore case
      • Not equals
      • Not equals ignore case
      • Contains
      • Exists
      • Greater Than
      • Less Than
    • Value. Specifies a plain value or value with a syntax.

    For details about the variables available in API Gateway, see Variables Available in API Gateway.

  8. Click Custom Variable.

  9. Provide the following information in the Define Custom Variable section, as required:

    Property Description
    Custom Variable Specify the custom variable with a syntax to be accessed across subsequent stages and click Add.
    • Variable. Specifies the custom variable with a syntax.
    • Value. Specifies a plain value or value with a syntax.
    For example, if you want to use the client’s request related information like content-type header at response stage, you can define the ${clientContentType} custom variable to store the ${request.headers.Content-Type} variable. The ${clientContetType} custom variable can be accessed in any other policy across subsequent stages such as response or error processing stage. For details about the variables available in API Gateway, see Variables Available in API Gateway.
  10. Provide the following information in the Custom Extension Metadata section, as required. This is applicable only for XML transformation:

    Property Description
    Namespace Prefix Provide the namespace prefix of the payload expression to be validated.
    For example, specify the namespace prefix as SOAP_ENV.
    Namespace URI Provide the namespaceURI of the payload expression to be validated. For example, specify the namespace URI as http:// schemas.xmlsoap.org/soap/envelope/. This declaration defines SOAP_ENV as an alias for the namespace:http://schemas.xmlsoap.org/soap/envelope/.
  11. Click Save.
    The API is saved with the added custom extension.

  12. Invoke the API.
    The custom variables are defined and can be accessed in the subsequent policy stages.

Custom Extension Properties

The table lists the properties that you can specify for a custom extension.

Request Processing Section

The table lists the custom extension properties you can configure in the Request processing section:

Property Description
Payload Provide the request payload to be sent to the custom extension in one of the following ways:

  • Type the request payload in the text box.

    For details on the data objects and variables available in the Request Processing section that you can use to configure, see Data Objects and Variables Available in API Gateway.

  • Click and select one of the following and provide the required information:

    • Inline Request. Type the required payload.

    • Load from Schema. Click Browse to upload a JSON or XML schema file and click Save.
Headers Provide the following information, if you want to configure the headers you need to send to the custom extension. By default, no headers are sent to the custom extension.

  • Select Use incoming headers to use the header content in the incoming requests from the client.

  • Provide the Header Name and the Header Value in the incoming client request that has to be processed.
Query Parameters Provide the following information, if you want to configure query parameters you need to send to the custom extension.

  • Provide the Query Parameter Name and the Query Parameter Value in the incoming client request that has to be processed.
For details on the data objects and variables available in the Request Processing section that you can use to configure, see Data Objects and Variables Available in API Gateway.

Response Processing section

The table lists the custom extension properties you can configure in the Response Processing section:

Property Description
Copy the entire response Select to copy the entire response received from the external call out. This response is used in the subsequent step by using ${request.payload} or ${response.payload}.

Note: Do not select this if you are using AWS Lambda custom extension with invocation type as Event as there is no response returned.
Abort API execution in case of failure Select to abort the API execution when the external callout encounters any failures. If you do not select this option, API Gateway logs the failure and continues with the processing.
Transformation Specify the following custom variables with a syntax to be accessed from the response of the custom extension and click Add.

  • Variable. Specifies the variable type with a syntax.

  • Value. Specifies a value with a syntax.
For example if you provide a variable as ${var} and the corresponding value as ${response[customPolicy].payload.jsonPath[$.id]}, this transformation evaluates the JSON path from the custom policy response payload to get the value of the attribute id. The evaluated value is assigned to the variable var given in the Variable field. You can use the ${var} syntax in the subsequent policies that support variable framework.
For details about the data objects and variables available in the Response Processing section that you can use to configure, see Data Objects and Variables Available in API Gateway.
Custom extension metadata This is used for XML transformation.

  • Namespace Prefix. Provide the namespace prefix of the payload expression to be validated.

  • Namespace URI. Provide the namespace URI of the payload expression to be validated.

Custom Extension Metadata section

The table lists the custom extension properties you can configure in the Custom Extension Metadata section. This is applicable only for XML transformation:

Property Description
Namespace Prefix Provide the namespace prefix of the payload expression to be validated.
Namespace URI Provide the namespace URI of the payload expression to be validated.

For details about the data objects and variables that you can use to configure, see Data Objects and Variables Available in API Gateway.

Data Objects and Variables Available in API Gateway

The following table summarizes the data objects and variables that are available in API Gateway:

Object/Variable type Possible values
paramStage
  • request

  • response
paramType
  • payload or body

  • headers

  • query

  • path

  • httpMethod

  • statusCode

  • statusMessage
queryType
  • xpath

  • jsonPath

  • regex

The following data objects are available in the request processing or response processing steps: - ${paramStage.paramType} You can use this syntax to access the following string variables: path, statusCode, statusMessage, httpMethod. Examples: ${request.path}, ${response.statusCode}.

Team Support

The Team Support feature allows you to group the users who work in a project, or users with similar roles, as a team. 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 teams, 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. A team can be defined as a group of users with a set of defined responsibilities.

You can create teams from the User Management section of API Gateway by including the required user groups and assigning them the required functional privilege. 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:

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

The team, Default, is available in API Gateway when the feature is enabled and all API Gateway users are added to this team by default. Assets, which are not assigned to any team, are assigned to the Default team. Hence, all API Gateway users can view the assets that are part of the Default team. However, users can perform actions on the assets based on the functional privileges assigned to them.

The assets supported by this feature are: APIs, Applications, Packages, and Plans.

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

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 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.

Before you begin

Ensure that you have:

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. Click Continue to assign functional privileges >.
    The Functional privileges list appears.

  7. Select the functional privileges to be assigned to the team members. For information on the available functional privileges, see API Gateway Functional Privileges.

    For this use case, we 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.

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

  9. 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 is selected.

  10. Click Save. Team with specified details is created. As per the values provided in our use case, the DevTeam is created and appears in the list of teams.



    After team creation, you can 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:

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. The example asset, DevAPI is created by importing a file.

  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 the use case considered, DevTeam is selected in the field.



    The assigned teams appear in the Team field of Basic Information section in the API details page. In our 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 being created. As stated earlier, you can create rule by specifying a set of required conditions. Assets will be validated against the given conditions and they will assigned to the configured teams. If you do not provide any conditions when for a rule, the rule will be 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:

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.

  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 Operator that required to validate the attribute against the given value. The available options are:

    • Equals. Checks if the name or description of asset is equal to the given value.

    • Contains. Checks if asset contains the given value as a part of its name or description.

    • Start with. Checks if asset name or description starts with the given value.

    • Ends with. Checks if asset name or description ends with the given value.
    Value Value of the attribute.

    For the use case considered in this section, 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 we considered, 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

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 our example, the API-Gateway-Providers from is selected.

    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://host:port/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.

Enabling Teams Support

Once you enabled the Team feature, you can manage teams from the Teams tab under the User management section of API Gateway.

Note: The team feature is supported only for SAG Cloud provisioned tenants.

If you do not enable this feature, you can still create teams like 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 will be invalid. That is, the assets will be 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 Settings section.

  5. Type true in the enableTeamWork field. By default, the value of the setting is set as false.
    The feature is enabled.

Team Support Considerations

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

Visibility and Accessibility of Assets

As stated in previous sections, when an asset is assigned to one or more teams, only the members of the assigned teams will have access to the assets based on their functional privileges. This would also be applicable in the global search field. When you search an asset using a keyword, the search will return only the assets that are assigned to your teams.

Also, when you manage features for an asset like Polices, API Mashup, and Applications where assets that do not belong to your team are involved, you can view those assets. However, you cannot perform any action on the assets that do not belong to your team.

For example, consider an application assigned to your team is created with more than one API and only one of those APIs is assigned to your team. In such cases, you can view the APIs that are used to create the application; and you will have no access to the APIs that are not a part of your team(s).

Importing and Exporting of Teams and Assets

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

Promoting of Assets

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

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 API 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.

API First Implementation

APIs form the nerve center of software applications. So, it is very important for the providers to be clear about what they would provide and consumers to be clear about what they want to consume. Better understanding of APIs guarantee an excellent output. API First is all about the establishment of a common agreement between the providers and consumers. Thus, this design helps both the parties to be on the same page.

When adapting API First approach, API developers start the API development with the API contract and work on the implementation part at a later stage. This approach of prioritizing the API design over its implementation is beneficial to both, providers and consumers.

In conventional scenarios, providers expose APIs to their consumers only after the API is implemented. Consumers test the API and let the providers know their feedback about the API. Providers must then revisit the API to incorporate the feedback received from their consumers. You can optimize this process by adapting API First design.

When following API First approach, consumer does not have to wait for the provider to implement the API, they can proceed with their application development using the exposed API. The implementation status of API does not have an impact on consumers as they receive the designated responses for their requests through the mocked API. So, the API development and the application development can take place at the same time.

Once the provider implements the API, the end-point is updated to divert the invocations to the actual implementation instead of mocked response. The provider can then disable mocking.

The following diagram explains the flow of API development as per the API First design:

As per the API First design, providers expose their API to consumers when the development is underway.

API First Design using API Gateway

Starting API Gateway 10.5, the application provides seamless support for API First approach for your APIs.

Using API Gateway, you can define API contract for the APIs and download provider specification for the APIs that you create. As a provider, you would not want to expose all resources and methods of an API to consumers. The API Contract given to the consumer has only the part of API exposed to the consumer whereas the provider specification comprises of the complete specification. This is useful for providers to implement the API.

You can enable mocking and activate the API for consumption. The mocked version of API returns respective responses for the consumer requests. This ensures the required end-user experience to the consumers.

When the API is ready to be implemented, you can implement your APIs in Integration Server or any other implementation server. If you are using Integration Server, you can add the required Integration Server instance in API Gateway. You can add multiple Integration Server instances and publish your API to the required instance. If you are using Integration Server, you can send the API contract from API Gateway. Else, the API contract has to be retrieved from API Gateway.

After implementation, you can update the actual implementation end-point to API Gateway. This step is mandatory to disable API mocking and divert the invocations to the actual end-point.

The following workflow shows the high-level workflow of API First implementation approach using API Gateway:

API First Implementation using Integration Server

This use case explains the steps involved in adapting API First from Integration Server. When an API created in API Gateway is implemented in Integration Server, then the API Contract is sent from API Gateway to Integration Server.

The use case starts when you create an API in API Gateway and ends when you communicate the API implementation endpoint to API Gateway.

In this example, the APIFirst API is created in API Gateway and implemented in the Integration Server instance, IS1 that is configured in API Gateway.

Before you begin

To adapt API First design using Integration Server

  1. Log on to API Gateway.

  2. Click APIs in the title navigation bar. A list of all existing APIs appears.

  3. Click Create API to create an API with required API documentation.

  4. Click Policies and define required policies for the API.

  5. Click Enable Mockingto mock and generate API mock responses. This step enables the API to send responses to the requests received from consumers.

  6. From the APIs page, click Publish for the APIFirst API. The Publish API dialog box appears.

  7. Select Integration Servers. The list of configured Integration Servers instances appears.

  8. Select the IS1 instance from the list.

  9. In the Package Name and Folder Name fields, provide the package name and folder name of the IS instance in which the API must be implemented. The API along with the API contract is published to Integration Server.

  10. After implementing the API in Integration Server, invoke the REST end-point to communicate API implemented endpoint to API Gateway:

    PUT http://<API Gateway host>:<port>/rest/apigateway/apis/{apiId}/implementation
    {
        
    "maturityState": "string",
    "nativeBaseURLs": [
    "string"
    ]
    }   

    You can provide required values for the parameters in the above command. For information on parameters, see List of Parameters used in API Implementation.

    Example:

    PUT http://10.2.151.149:5555/rest/apigateway/apis/
    94dfd243-dd54-4d7e-8ba5-396ffaf6fe4e/implementation
    {
    "nativeBaseURLs":["https://10.2.35.125:5556/ws/srvs:Calculator/
    CalculatorHttpSoap11Endpoint",
    "http://10.2.151.149:5555/ws/srvs:Calculator/CalculatorHttpSoap11Endpoint"],
    "maturityStatus" : "Implemented"
    }

    As a result of the REST call, the mocking of the API is disabled and the consumers requests are directed to the actual implementation.

API First Implementation using a Third-party Server

This use case explains the steps involved in adapting API First approach using a third-party implementation server.

The use case starts when you create an API in API Gateway and ends when you communicate the API implementation endpoint to API Gateway.

Before you begin

To adapt API First design using a third-party implementation server 1. Log on to API Gateway.

  1. Click APIs in the title navigation bar. A list of all existing APIs appears.

  2. Click Create API to create an API with required API documentation.

  3. Click Policies and define required policies for the API.

  4. Click Enable Mocking to mock and generate API mock responses.

  5. Using an external REST client such as Postman or SoapUI, run the below command to search for the API in API Gateway for implementation:

    POST http://<API Gateway host>:<port>/rest/apigateway/search
    {
    "types" : ["api"],
    "scope" : [
    {
    "attributeName" : "maturityState",
    "keyword" : "ToBeImplemented"
    }
    ]
    }

    The maturityState parameter in the above command is used search for APIs based on their maturity state. In this use case, we must search for APIs that are to be implemented. Hence, we can provide the ToBeImplemented value for the parameter. This command returns the list of APIs that are yet to be implemented.

  6. Using the API Id of the API that you want to implement, run the following command to retrieve the API contract from API Gateway:

    GET http://<host>:<port>/rest/apigateway/apis/{apiId}/
    providerspecification?format=swagger

    The value for the format parameter can be swagger, raml, or openapi for REST APIs; and wsdl for SOAP APIs.

    Note: You can search for an API based on its maturity status in API Gateway using the following command:

    POST http://<API Gateway host>:<port>/rest/apigateway/search
    {
    "types" : ["api"],
    "scope" : [
    {
    "attributeName" : "maturityState",
    "keyword" : "ToBeImplemented"
    }
    ]
    }
  7. Implement the API in the required implementation server.

  8. After implementation, invoke the REST end-point to communicate API implemented endpoint to API Gateway:

    PUT http://<API Gateway host>:<port>/rest/apigateway/apis/{apiId}/implementation
    {
        
    "maturityState": "string",
    "nativeBaseURLs": [
    "string"
    ]
    }

    You can provide required values for the parameters in the above command. For information on parameters, see List of Parameters used in API Implementation.

    Example:

    PUT http://10.2.151.149:5555/rest/apigateway/apis/
    94dfd243-dd54-4d7e-8ba5-396ffaf6fe4e/implementation
    {
    "nativeBaseURLs":["https://10.2.35.125:5556/ws/srvs:Calculator/
    CalculatorHttpSoap11Endpoint",
    "http://10.2.151.149:5555/ws/srvs:Calculator/CalculatorHttpSoap11Endpoint"],
    "maturityStatus" : "Implemented"
    }

As an outcome of the REST call, the mocking of the API is disabled and API Gateway starts requests for the actual implementation.

List of Parameters used in API Implementation

The following are some of the parameters used during API implementation:

Parameter Purpose
nativeBaseURLs Endpoint URLs of the native service. This parameter is mandatory to route the requests to this implemented API. The existing endpoint values of the routing policies of the API are replaced with the URLs given against this parameter. You can provide multiple HTTP and HTTPS URLs for this parameter. The URLs that you provide for this parameter appears under the Native endpoint(s) section in the Technical information page of API Gateway. The first URL among the list of URLs is used in the routing policies by this update call. If you want to use any other URL in the routing policies, you can update the API policies accordingly.
maturityState Indicates the maturity state of APIs. You can use this parameter to search for an API based on its maturity state and retrieve the API for implementation. Also, you can use this to update the maturity state of an API after implementation. Typically, the value of this parameter would be the consecutive state defined in the apiMaturityStatePossibleValues extended setting configuration.
For example,
If any of the following states are configured in the apiMaturityStatePossibleValues setting : Design, Implementation, Testing, Production; and current state of an API is Implementation, then you must specify Testing as the parameter value because that would be next stage as per the configuration.

Gateway Endpoints

Gateway endpoint is the URL that is used to access an API through API Gateway. By default, API Gateway provides a default gateway endpoint for all active APIs. The default gateway endpoint is in the <protocol>://<host>:<port>/{defaultPrefix}/{apiName}/{apiVersion}/{resourcePath} format.

When there is a need to access the API using a different endpoint, you can define a custom gateway endpoint. In custom gateway endpoints, you can customize the portion of the URL between <port> and <resourcePath>.

Custom gateway endpoints can be specific to an API or a global template can be defined through global gateway endpoint.

How do I Define API-specific Gateway Endpoints?

This use case explains how to define custom gateway endpoints specific to an API. You can define more than one custom gateway endpoint to an API. Custom gateway endpoints can be added for all types of APIs such as REST, SOAP, OData, and WebSocket.

The use case starts when you want to define API specific gateway endpoint and ends when you have created the API specific gateway endpoint.

Here are some points that you need to consider, when you define API specific gateway endpoint:

For example, when a gateway endpoint uses ${apiName} variable, and if you change the API name, it automatically gets reflected in the gateway endpoint.

Note: If you want to use a gateway endpoint across all versions of an API, Software AG recommends you to use the ${apiVersion} variable so that the gateway endpoint becomes unique across different versions.

Important: At any given point, API Gateway does not allow you to provide the same gateway endpoint for different APIs nor different versions of same API. Hence, make sure that you provide an unique gateway endpoint, so that it does not match with any of the existing APIs’ default or custom gateway endpoints.

Before you begin

Ensure that you have:

  • Manage APIs functional privilege.
  • Activated the API.
  • To define API-specific gateway endpoints

    1. Click APIs in the title navigation bar. A list of all registered APIs appears.

      Note: You can manage the gateway endpoints of an API, directly from the view mode of the API details screen.

    2. Click the corresponding API for, which you want to customize the gateway endpoint. The API details page appears.

    3. Click Technical information.

    4. Click +Add custom gateway endpoint and provide the following information.

      Field Description
      Name Specifies the name for the custom gateway endpoint. A gateway endpoint name must be unique within an API.
      URL Specifies the custom gateway endpoint.
      The gateway endpoint name cannot include a space, nor can it include the following special characters: # % ? ‘ “ < \

    5. Click Save. The added custom gateway endpoint appears in the Gateway endpoint(s) field of the API details page. In addition to the default gateway endpoint, you can access the API using this custom gateway endpoint.

      Note: You can edit or delete the gateway endpoint from API details page either by clicking the or icon corresponding to the gateway endpoint that you want to edit or delete.

    How do I Define Global Gateway Endpoint?

    This use case explains how to define global gateway endpoint. The global gateway endpoint creates gateway endpoint template for all APIs. Each API will inherit this global endpoint in addition to the default and custom endpoints of an API.

    The use case starts when you want to define global gateway endpoint and ends when you have created the global gateway endpoint.

    In order to generate a unique gateway endpoint for each API version, the global gateway endpoint template must use the following variables :

    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:

    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:

  • Design time events such as audit logs of API Gateway modules.
  • Destination specific details such as error events and policy violation events of assets, and Performance metrics data.
  • Traffic monitoring payloads and alerts of an API
  • 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.

    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:
    9. RequestResponse (synchronous type)
    10. Event (asynchronous type)
    11. AWS Alias Provide the AWS alias configured for the AWS account.

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

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

    13. 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.

    14. 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.

    Secure API using OAuth2 with refresh token workflow

    When using the authorization code grant type to get the access token, you need to get the permission from the resource owners at least for the first time. In the subsequent attempts to get the access token, if you do not want to get the permission from the resource owners, then you can use the refresh token.

    This use case explains how to secure the API using OAuth2 authentication strategy. It also explains the refresh token workflow in detail.

    Configuring OAuth2 Authentication with Refresh Token

    This use case explains how to secure the API using OAuth2 authentication strategy with authorization_code and refresh_token grant types.

    The use case starts when you create an API and ends when you create an application strategy with OAuth2 authentication scheme.

    To configure OAuth2 Authentication with Refresh Token

    1. Create an API. For details about creating an API, see Creating an Rest API.

    2. Enable the OAuth2 token identification type in the Identify & Authorize policy. For details about Identify & Authorize policy, see Identify & Authorize.

    3. Create OAuth scope in the local authorization server.

    4. Map the OAuth scope to the API scope. For details about mapping OAuth scope, see Mapping OAuth or OpenID Scopes.

    5. Create an application with OAuth2 authentication strategy.

      a. Create a new application.

      For details about creating an application, see Creating an Application.

      b. Associate the application with the API that you have created.

      c. Click the Authentication tab to create strategy with OAuth2 authentication.

      d. Select the Authentication schemes as OAUTH2.

      e. Specify the Authentication server as local.

      f. Enable the Generate credentials toggle button to generate the client dynamically in the authorization server and provide the following information:

      i. Select the Application Type as Confidential. A confidential client is an application that can keep a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password.

      ii. Select the application profile from the Application profile drop-down menu. For example, web.

      iii. Specify the duration in seconds for which the access token is active in the Token lifetime (seconds).

      iv. Specify the number of times you can use the refresh token in the Token refresh limit to get a new access token.

      Note:To use refresh token unlimitedly, specify the limit as -1.

      v. Specify the URIs that the authorization server can use to redirect the resource owner’s browser during the grant process. You can add multiple URIs by clicking +Add.

      vi. Specify the grant type to be used to generate the credentials. For this specific use case, we have selected authorization code, client_credentials, and refresh_token, which are dynamically populated from the authorization server.

      Note:Make sure you have selected refresh_token grant_type, if you want to get the refresh tokens.

      vii. Select the scopes that are to be mapped for the authentication strategy.

      viii. Click Add to save the strategy.

      ix. Click Save to save the application.

    Refresh Token Process Flow

    This use case explains the following workflow:

    How to get the access token with resource owner permission?

    This use case starts when you get the authorization code and ends when you access then API.

    To get access token using authorization code grant type (With resource owner permission)

    1. Get authorization code.

      a. Click the http(s)://hostname:port/invoke/pub.apigateway.oauth2/authorize?response_type=code&redirect_uri=<redirectURI>&client_id=<Client ID>. >Note: Make sure you have replaced the <redirectURI > and <ClientID > in the above mentioned URL. You can get the redirect URI and client ID from the Authentication tab of the Application screen.

      b. Click the Approve button.

      c. Enter the credentials of your API Gateway instance.

      You will be re-directed to the redirect URI as per to the configuration. The below screenshot is just a sample, you will be redirected to a different URL based on your configuration and so the screenshot varies accordingly . If the given redirect URI is not a valid web page, you may get a Page not found error, which is fine, because we get the authorization code value from the browser URL.

      d. Make a note of the authorization code that is displayed in the address bar of the browser. As highlighted in the above image’s URL, you can see the authorization code in the code= field of the URL.

    2. Get Access Token.

      a. Invoke the access token endpoint.

      Request: POST http(s):// hostname:port/invoke/pub.apigateway.oauth2/getAccessToken

      In the Authorization tab, select the authorization type as Basic Auth. Provide the client ID as username and client secret as password. You can get the client ID and client secret in the Authentication tab of the Application screen.

      Sample request body

      { "redirect_uri":"http://test.com", "scope":"email", "grant_type":"authorization_code", "code":"4b4b16c68f1c4b6fa7f26e0cb00b5daa" }

      Note:You must replace the redirect_URI, scope, and code with appropriate values. For the code field value, make sure you use the authorization code that you have noted down in the previous step.

      Sample response body

      { "scope": "TestRefreshtoken", "access_token": "c92b6227a19c46f1a6545bf370bb6ee6e30ff87957ef4b1aaa9577f7e86e4bd7", "refresh_token": "f78dd4fc5b8d4d799cf066427e828e26ce7e3723e4334416a7b9cd8a274e6947", "token_type": "Bearer", "expires_in": 3600 }

    3. Access API using the REST API client.
      In the Authorization tab, select the authorization type as Bearer Token and provide the access token that you get from the response payload of the previous step. .

      How to get the access token without resource owner permission using refresh token in the subsequent attempts?

    This use case starts when you get the authorization code and ends when you access then API.

    To get access token using refresh token (Without resource owner permission)

    When the access token expires and if you need to access the same API, you need to get another access token. If you have refresh token, you can get a new access token without getting the permission from the resource owner.

    1. Invoke the access token endpoint.

      Request: POST http(s)://hostname:port/invoke/pub.oauth/refreshAccessToken

      In the Authorization tab, select the authorization type as Basic Auth. Provide the client ID as username and client secret as password. You can get the client ID and client secret in the Authentication tab of the Application screen.

      Sample request body

      { "grant_type":"refresh_token", "refresh_token":"f78dd4fc5b8d4d799cf066427e828e26ce7e3723e4334416a7b9cd8a274e6947" }

      Note:Make sure you have replaced the refresh token that you got from the Step 2 using How to get the access token with resource owner permission? use case .

      Sample response body

      { "grant_type": "refresh_token", "refresh_token": "f78dd4fc5b8d4d799cf066427e828e26ce7e3723e4334416a7b9cd8a274e6947", "scope": "TestRefreshtoken ", "access_token": "c102bcaebecf451ca705bf54d26fae732ea9790a0ff64a87a010b3875b4b8da2", "token_type": "Bearer", "expires_in": 3600 }

    2. Access API using the REST API client.
      In the Authorization tab, select the authorization type as Bearer Token and provide the access token that you get from the response payload of the previous step. .

    Securing Access Token Calls with PKCE

    PKCE (Proof Key for Code Exchange) is a mechanism that prevents Authorization Code Interception attacks and makes OAuth 2.0 authorization code grant more secure for public clients. The client application should give proof to the authorization server that the authorization code belongs to the client application. Only then the authorization server issues an access token for the client application.

    The PKCE flow works with these parameters:

    The flow chart explains the Get Access Token workflow in API Gateway using authorization code grant type with PKCE.

    How do I enforce PKCE globally?

    This use case explains how to enforce PKCE globally in the local authorization server. When you enforce PKCE at global level, then it is applied for all the public OAuth2.0 clients of local authorization server.

    This use case starts when you want to enable the PKCE workflow and ends when you get the access token on successful validation.

    To enforce the PKCE at global level

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

    2. Select Security > JWT/OAuth/OpenID. The Authorization servers section displays a list of available internal and external authorization servers.

    3. In the Internal authorization servers section, click local .

    4. Expand the OAuth configurationsection, select the Enforce PKCE checkbox.

    5. Click the Update button. Once you enforce PKCE, you get access token only on successful validation of code verifier.

    How do I secure the access token with Authorization Code (With PKCE) grant type using postman?

    This use case starts when you enforce the PKCE and ends when you get access to the token securely using postman.

    To secure the access token

    1. Create OAuth scope in the local authorization server.

    2. Create an application with OAuth2 authentication strategy. For details about creating an application, see Creating an Application.

      a. Click the Authentication tab in the Application details window to create a strategy with OAuth2 authentication.
      Make sure you have selected the following mandatory fields for this use case:

      • Select the Authentication schemes as OAUTH2.
      • Specify the Authentication server as local.
      • Select the Application Type as Public.
      • Specify the grant type to be used to generate the credentials. For this specific use case, you must select authorization_code, which is dynamically populated from the authorization server.
      • Specify the postman https://oauth.pstmn.io/v1/callback URL as redirect URI.
      • Specify the OAuth scope that you have created for the local authorization server in Step 1.

      b. Click Add to save the strategy.

      c. Click Save to save the application.

    3. In the Postman, under the Authorization tab, select the authorization type as OAuth2.0 from the TYPE drop-down menu.

      a. In the Configure New Token section, select the grant type as Authorization Code (With PKCE).

      b. Type the redirect URL as https://oauth.pstmn.io/v1/callback in theCallback URLtext box .

      c. Select the Authorize using browser check box

      d. Type the authorization URL as http(s)://hostname:port/invoke/pub.apigateway.oauth2/authorize in the Auth URL text box

      e. Type the http(s)://hostname:port/invoke/pub.apigateway.oauth2/getAccessToken in the Access Token URL text box.

      f. Type the client ID and client secret in the Client ID and Client Secret text boxes respectively.

      Note: You can get the client ID and client secret from the Authentication tab of the Application screen.

      g. Select the hashing method used to generate the code challenge from the Code Challenge Method drop down menu.

      h. Specify the OAuth scope that you have created for the local authorization server in Step 1 in the Scope text box.

      i. Select the client authentication as Send client credentials in body .

      j. Click the Get New Access Token button.

      k. Click the Approve button. TheMANAGE ACCESS TOKENS pop-up window displays the access token.

    How do I secure the access token by directly calling API Gateway’s REST APIs?

    This use case starts when you enforce the PKCE and ends when you get access the token securely using REST APIs.

    Before you begin

    Ensure that you have:

    To secure the access token

    1. Create OAuth scope in the local authorization server.

    2. Create an application with OAuth2 authentication strategy. For details about creating an application, see Creating an Application.

      a. Click the Authentication tab to create a strategy with OAuth2 authentication. Make sure you have selected the following mandatory fields for this use case:

      • Select the Authentication schemes as OAUTH2.
      • Specify the Authentication server as local.
      • Select the Application Type as Public.
      • Specify the grant type to be used to generate the credentials. For this specific use case, you must select authorization_code, which are dynamically populated from the authorization server.
      • Specify the URIs that the authorization server can use to redirect the resource owner's browser during the grant process. You can add multiple URIs by clicking +Add.
      • Specify the OAuth scope that you have created for the local authorization server in Step 1.

      b. Click Add to save the strategy.

      c. Click Save to save the application.

    3. Get authorization code.

      a. Call the authorize endpoint using a REST client.
      http(s)://hostname:port/invoke/pub.apigateway.oauth2/authorize? response_type=code&redirect_uri=&client_id=&code_challenge=&code_challenge_method=S256

      Note: Make sure you have replaced the redirectURI , ClientID, and Code_Challenge in the above mentioned URL. You can get the redirect URI and client ID from the Authentication tab of the Application screen.

      b. Click the Approve button

      c. Provide the credentials of API Gateway user to approve the request.

      You are re-directed to the redirect URI as per the configuration in the application strategy. The screenshot below is just a sample, you are redirected to a different URL based on your configuration, so the screenshot varies accordingly. If the given redirect URI is not a valid web page, you might get a Page not found error, which is fine, because we get the authorization code value from the browser URL.

      d. Make a note of the authorization code.

      Note: If the redirect URL screen is not able to display the authorization code, then you can take it from the address bar of the browser. As highlighted in the above image’s URL, you can see the authorization code in the code=field of the URL.

      e. Click Save to save the application.

    4. Get access token.

      a. Invoke the access token endpoint using a REST client.
      Request: POST http(s)://hostname:port/invoke/pub.apigateway.oauth2/getAccessToken.

      In the Authorization tab, select the authorization type as Basic Auth . Provide the client ID as username and client secret as the password. You can get the client ID and client secret in the Authentication tab of the Application screen.

      Sample request body

          
      
      {
          
      
      "redirect_uri":"http://test.com",
          
      
      "scope":"email",
          
      
      "grant_type":"authorization_code",
          
      
      "code":"0025abe9f96d4901b61340344c29a576",
          
      
      "code_verifier":"a4793f15479a4c5697f93b44d055ab6cbd16be50400a4591892f914b1a256da8",
          
      
      "client_id":"374b1fae-4405-411b-85a0-6e1ab90923ba"
          
      
      }
          

      Note: You must replace the redirect_URI, scope, code, and code_verifier with appropriate values. For the code field, make sure you use the authorization code you noted down in the step 3.d.

      Sample response body

          
      
      {
          
      
      "access_token": "b5b33bc9c57945f388010f8caf5fe9b6b14abef468d346e68e0cd374c0df60d7",
          
      
      "token_type": "Bearer",
          
      
      "expires_in": 3600
          
      
      }
          

    How do I enforce PKCE selectively for each access token call?

    You can enforce PKCE specific to each GET access token call. To perform this use case, you must clear the Enforce PKCE check box in the Administration > Security > JWT/OAuth/OpenID screen. When you disable the PKCE global option, by default PKCE is not verified. But if you send the authorize request with the code challenge and code challenge method parameters, you get an access token with PKCE verification even though you have not enforced PKCE.

    How do I generate code verifier and code challenge?

    To generate code verifier and code challenge

    1. You can generate code verifier and code challenge using the Postman tool. You can select the code challenge method and postman automatically generates the code verifier for you. For more details, see How do I secure the access token with Authorization Code(With PKCE) grant type using postman?.

    2. Additionally, If you want to create a code verifier and code challenge on your own, please follow the instructions available in the PKCE RFC document RFC 7636, particularly sections 4.1 and 4.2

    Trace API

    With Trace API support, you can monitor the complete life cycle of the runtime requests within API Gateway. This use case explains how to trace an API call in API Gateway. You can perform tracing for any runtime requests. Inspecting the failed runtime requests help you to debug and troubleshoot your API calls. You can trace REST, SOAP, and OData API calls only.

    On enabling the tracer for an API, you can view the list of runtime requests that invoked the API. For each request, you can view

    Important considerations when you trace an API:

    The following policies are covered as part of trace API:

    How do I enable tracing?

    This use case starts when you want to enable trace for an API and ends when you view the trace details for that API.

    Before you begin

    Ensure that you have:

    To enable tracing

    1. Click APIs in the title navigation bar.

    2. Click an API for which you want to enable the trace.
      The API details page displays the basic information, technical information, resources and methods, and specification for the selected API.

    3. Click the Enable tracing button.
      Once you have enabled the tracer, the API details page displays the warning message, This API has tracing enabled. Tracing impacts performance and storage, hence disable tracing when it is not needed.

    4. Click the Tracer tab to view the trace details.
      The Trace API page displays the Runtime events, Policies applied, and Event tracer details sections.

      Note: When you enable tracer, API Gateway captures a large amount of data, which might impact the performance and availability of the product. Hence Software AG strongly recommends you to disable the tracer when not needed.

    How do I filter the runtime request?

    This use case starts when you want to filter the client request based on its runtime events and ends when you view the trace details of the filtered client request.

    To filter the runtime event

    1. Click the Tracer tab.
      The Trace API page displays the Runtime events , Policies applied , and Event tracer details sections.

    2. In the Runtime events section, click to filter the runtime events.
      The Apply filter pop-up window displays.

    3. To filter the runtime events, click and select the time interval using the options:

      • Quick select. Specify the time interval. Click Apply to filter the runtime events based on the time interval.
      • Commonly used. Select a commonly used time interval, and the filter is applied automatically. To view the runtime events between a time interval, click Custom range > From Date > To Date > Apply .
      • The Runtime events section displays the list of runtime events based on the applied filter.

        The runtime events are displayed using various legends to indicate the different types of requests along with their status code.

        The below table displays the legends and their description:

        Legends Description
        Successful API calls
        Failed API calls due to client-side errors
        Failed API calls due to Server-side errors
        Redirection calls
        Informational calls

    How do I view the trace details?

    This use case starts when you want to view the stage-wise and policy-wise trace details about the selected client request and ends when you view the trace details at the policy level.

    Before you begin

    Ensure that you have:

    To view the trace details

    1. In the Runtime events section, click the client request for which you want to view the trace details.
      The Trace API page refreshes and populates data in the Policies applied and Event tracer details sections. By default, the Event tracer details section displays the General Information, API request and response, and Server logs sections. Under the API request and response section, you have the following sub-sections:

      • Request sent by client. Displays the request headers and request body sent by the client to API Gateway.
      • Response sent to client. Displays the response headers and response body sent to the client from API Gateway.
      • Request sent to native service. Displays the request headers and request body sent to the native API from API Gateway.
      • Response sent by native service. Displays the response headers and response body sent by the native API to API Gateway.

      Note: If the request and response body has streaming content, the tracer does not capture the streaming content even if you have enabled the tracer.

    2. In the Policies applied section, click the stage name for which you want to view the trace details.

      The Trace API page refreshes the Event tracer details section with the stage_ name stage execution status section displaying the status and response time of the stage and policies that are enforced during API invocation.

      Note:

      • In the Policies applied section, if no policies is enforced in a stage during the invocation then that stage is disabled. In this use case, Error Handling stage is disabled.
      • The Status column indicates that whether the corresponding policy is invoked or not. If the Status column displays , it indicates that the corresponding policy is enforced successfully during invocation but it does not mean that the conditions specified in the policy are matched. You can click the respective policy to know more details on how the conditions were applied during invocation.

    3. In the Policies applied section, click the policy name for which you want to view the trace details.
      The Trace API page refreshes the Event tracer details sections with the policy_name policy config/input/output section displaying the configuration details, values that were passed as input before the enforcement of the policies and values that were transformed at the end of the policy enforcement, conditions and transformations that were applied and performed at the time of invocation, and payloads.

      Note: The template of the policy_name policy config/input/output section varies based on the policy

    How do I inspect failed runtime requests using tracer?

    This use case starts when you want to inspect the failed runtime request and ends when you debug and troubleshoot the failed API requests.

    To inspect the failed runtime request

    1. In the Runtime events section, click the client request for which you want to inspect the trace details.
      The Trace API page refreshes and populates data in the Policies applied and Event tracer details sections. By default, the Event tracer details section displays the General Information, API request and response, and Server logs sections. Under the API request and response section, you have the following sub-sections:

      • Request sent by client. Displays the request headers and request body sent by the client to API Gateway.
      • Response sent to client. Displays the response headers and response body sent to the client from API Gateway.
      • Request sent to native service. Displays the request headers and request body sent to the native API from API Gateway.
      • Response sent by native service. Displays the response headers and response body sent by the native API to API Gateway.

      Note: If the request and response body has streaming content, the tracer does not capture the streaming content even if you have enabled the tracer.

    2. In the Policies applied section, click the stage name highlighted in red for which you want to inspect the trace details.

      The Trace API page refreshes the Event tracer details section with the stage_ name stage execution status section displaying the status and response time of the stage and policies that failed during API invocation.

      Note: In the Policies applied section, if no policies in a stage is enforced during the invocation then that stage is disabled. In this use case, Response Processing stage is disabled and it is not enforced as the API invocation fails in the Routing stage. The Error Handling stage was enforced in order to handle the Routing stage failure.

    3. In the Policies applied section, click the policy name request highlighted in red for which you want to inspect the trace details.
      The Trace API page refreshes the Event tracer details sections with the policy_name policy config/input/output section displaying the configuration details, values that are passed during the enforcement of that policy, transformation conditions, and payloads. It also highlights the exact location where the policy invocation failed along with the failure reason.

    Note: The template of the policy_name policy config/input/output section varies based on the policy

    How do I import runtime requests?

    This use case starts when you want to import the client request from any other API Gateway instance to your API Gateway instance and ends when you view the trace details for the imported request.

    Before you begin

    Ensure that the imported request’s API ID matches with the API ID to which you import the request. The API type must also match with the API to which you import the archived request. If the imported request’s API ID or API type doesn’t match with the existing API, API Gateway rejects the import request.

    To import the runtime request

    1. Click the Tracer tab.
      The Trace API page displays the Runtime events, Policies applied, and Event tracer details sections.

    2. In the Runtime events section, click to import the archived runtime request.
      The Import and view events pop-up window displays.

    3. Browse the runtime request file that you want to import.

      Note: Make sure the file that you import does not exceed 50 MB.

    4. Click the View button.
      The imported request gets displayed in the Runtime events section.

    How do I export or download runtime requests?

    This use case starts when you want to export the client request from your API Gateway instance to your local machine and ends when you import the request in another API gateway instance.

    To export the runtime request

    1. Click the Tracer tab.
      The Trace API page displays the Runtime events, Policies applied, and Event tracer details sections.

    2. In the Runtime events section, select the runtime event that you want to export.

      Note: The Runtime events section lists only 20 runtime events per page. When you click Select all check box, all the runtime events of the API do not get selected. Instead, the 20 runtime events that are listed in that particular page gets selected.

    3. Click to export the runtime request. The selected request is downloaded to your local machine in a predefined location.