Administration

Various aspects of the way API Gateway functions can be configured:

  • General configuration for extended settings, service faults, approval settings, URL aliases.

  • Security configuration for keystores and trustore, SAML issuer, custom assertions, OAuth 2.0, Kerberos settings, JWT, and OpenID provider.

  • Destination configuration for targets to which the events and performance metrics data is sent.

  • External accounts to add and configure service registries.

You must have the API Gateway’s manage general administration configurations functional privilege assigned to perform the following configurations in the general configuration section of API Gateway:

  • Configure the extended settings which are advanced parameters required for your server to operate properly.

  • Configure API fault settings for errors being returned by the API Gateway to the applications.

  • Configure approval settings.

  • Configure URL aliases.

  • Configure the custom content-types.

  • Configure API callback request settings.

Custom Domains

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

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

How to configure Custom Domains?

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

Steps to configure custom domains:

  1. Determine the number of domains to be configured for your account and the list of custom domains.
    The domain names are owned by you.

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

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

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

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

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

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

Checks for existing assets after configuring custom domains

Allowed IP Addresses

Overview

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

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

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

Tenant URL and Software AG Cloud Region

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

Sample Tenant URL Software AG Cloud Region
Non CA3S based:
https://tenantname.gateway.webmethodscloud.com/apigatewayui/#/login

CA3S based:
https://tenantname.apigw-aw-us.webmethods.io/apigatewayui/#/login
US1 Oregon AWS
Non CA3S based:
https://tenantname.gateway.webmethodscloud.de/apigatewayui/#/login

CA3S based:
https://tenantname.apigw-aw-eu.webmethods.io/apigatewayui/#/login
EU2 Frankfurt AWS
https://tenantname.apigw-az-au.webmethods.io/apigatewayui/#/login AU1 Australia East Azure
https://tenantname.apigw-az-us.webmethods.io/apigatewayui/#/login US2 East Azure
https://tenantname.apigw-az-eu.webmethods.io/apigatewayui/#/login EU3 West Azure

Configuring Extended Settings

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

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

To configure the extended settings

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

  2. Select General > Extended settings.

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

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

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

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

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

  6. Click Save.

Configuring API Fault Settings

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

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

To configure the service fault settings

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

  2. Select General > API fault.

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

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

  5. Click Save.

Approval Configuration

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

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

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

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

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

Configuring Approvals for Creating Application

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

To configure approvals for creating an application

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

  2. Select General > Approval configuration > Create application.

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

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

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

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

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

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

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

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

    Field Description
    Send notification To send an email notification to the approver to approve the request for creating an application.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.

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

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

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

    Field Description
    Send notification To send an email notification to the requester that the request for creating an application is approved by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Create Application in the email sent, where Create Application is the event.type.
  12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for creating an application is rejected.

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

    Field Description
    Send notification To send an email notification to the requester that the request for creating an application is rejected by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Create Application in the email sent, where Create Application is the event.type.
  14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

  15. Click Save.

Configuring Approvals for Registering Application

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

To configure approvals for registering an application

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

  2. Select General > Approval configuration > Register application.

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

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

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

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

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

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

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

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

    Field Description
    Send notification To send an email notification to the approver to approve the request for associating an application with APIs.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.

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

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

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

    Field Description
    Send notification To send an email notification to the requester that the request for associating an application with APIs is approved by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Register Application in the email sent, where Register Application is the event.type.
  12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for registering an application is rejected.

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

    Field Description
    Send notification To send an email notification to the requester that the request for associating an application with APIs is rejected by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Register Application in the email sent, where Register Application is the event.type.
  14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

  15. Click Save.

Configuring Approvals for Updating Application

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

To configure approvals for updating an application

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

  2. Select General > Approval configuration > Update application.

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

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

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

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

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

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

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

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

    Field Description
    Send notification To send an email notification to the approver to approve the request for modifying an existing application.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.

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

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

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

    Field Description
    Send notification To send an email notification to the requester that the request for modifying an existing application is approved by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Update Application in the email sent, where Update Application is the event.type.
  12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for modifying an existing application is rejected.

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

    Field Description
    Send notification To send an email notification to the requester that the request for modifying an existing application is rejected by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Update Application in the email sent, where Update Application is the event.type.
  14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

  15. Click Save.

Configuring Approvals for Subscribing Package

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

To configure approvals for subscribing a package

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

  2. Select General > Approval configuration > Subscribe package.

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

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

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

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

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

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

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

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

    Field Description
    Send notification To send an email notification to the approver to approve the request for subscribing a package.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.

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

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

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

    Field Description
    Send notification To send an email notification to the requester that the request for subscribing a package is approved by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Subscribe Package in the email sent, where Subscribe Package is the event.type.
  12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for subscribing a package is rejected.

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

    Field Description
    Send notification To send an email notification to the requester that the request for registering an application is rejected by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Subscribe Package in the email sent, where Subscribe Package is the event.type.
  14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

  15. Click Save.

Configuring Approvals for Updating Subscription

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

To configure approvals for updating a subscription

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

  2. Select General > Approval configuration > Update subscription.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Configuring Approvals for Deleting Subscription

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

To configure approvals for deleting a subscription

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

  2. Select General > Approval configuration > Delete subscription.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Before you begin

Ensure that you have administrator privileges.

To configure the approval process for ownership changes of assets

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

  2. Select General > Change owner/teams.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  11. Click Save.

Approval Requests

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

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

Request types Users who can view and approve requests
Create application
Update application
Update subscription
Delete subscription
  • Team approvers. Approvers from the teams that the application is associated with. You can specify the team members who can approve the pending requests in the Approvers section of the Basic information tab when creating or editing team details.
  • Team administrators. Administrators of the team that the application is associated with. This includes the list of the users and user groups specified in the Team Administrators section of the Basic information tab when creating or editing team details. The team administrators can approve the pending requests only when you have selected the Include team administrators as approvers option.
Register application
  • Team approvers. Approvers from the teams that the API is associated with. You can specify the team members who can approve the pending requests in the Approvers section of the Basic information tab when creating or editing team details.
  • Team administrators. Administrators of the team that the API is associated with. This includes the list of the users and user groups specified in the Team Administrators section of the Basic information tab when creating or editing team details. The team administrators can approve the pending requests only when you have selected the Include team administrators as approvers option.
Subscribe package
  • Team approvers. Approvers from the teams that the package is associated with. You can specify the team members who can approve the pending requests in the Approvers section of the Basic information tab when creating or editing team details.
  • Team administrators. Administrators of the team that the package is associated with. This includes the list of the users and user groups specified in the Team Administrators section of the Basic information tab when creating or editing team details. The team administrators can approve the pending requests only when you have selected the Include team administrators as approvers option.

To approve or reject a pending request

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

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

    Field Description
    Requested by The name of the requestor.
    Requestor comments The additional information or comments added by the requestor.
    Event The type of event for which the request is pending.
    Request details The details of the type of event requested.
  3. Click the Approve or Reject icon to approve or reject requests.
    Alternatively, you can select multiple pending requests to be approved or rejected simultaneously by selecting the check boxes adjacent to the names of the requests. The request gets removed from the Pending requests page.

Deleting Requests

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

To delete a request

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

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

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

  4. Click Yes in the confirmation dialog.

URL Aliases

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

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

URL aliases have several benefits:

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

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

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

Creating URL Alias

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

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

To create a URL alias

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

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

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

    Field Description
    Alias The alias name of the proxy server.

    An alias name must be unique across API Gateway.

    The alias name cannot include a space, nor can it include the following characters: # % ? ‘ “ < \

    The alias name cannot begin with the string http:// or https://.
    Default URL path The URL path to the API on API Gateway.

    You must specify the default URL path if you do not define any port mappings for the URL alias. If the URL alias includes port mappings, the Default URL Path field is optional.

    The URL path cannot include a space or the following characters: # % ? ’ “ < |
  4. Click Save.

Enabling Partial Matching of URL Aliases

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

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

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

https://MyHost:9072/calc/deleteCalc

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

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

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

Modifying a URL Alias

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

  2. Select General > URL aliases.

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

  4. Incorporate the required changes.

  5. Click Save.

Deleting a URL Alias

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

  2. Select General > URL aliases.

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

  4. Click Yes in the confirmation dialog box.

Example - Usage Scenarios of URL Aliases

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

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

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

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

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

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

  2. Select General > URL aliases.

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

    Field Value
    Alias calc
    Default URL path gateway/RESTCalcService/1.0/postCalc
  4. Click Save.

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

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

Custom Content-types

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

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

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

Content-type Identifier Payload validation
  • application/xml
  • text/xml
  • text/html
  • multipart/form-data
  • multipart/mixed
XPath XML schema
  • application/json
  • application/json/badgerfish
JSONPath JSON schema
text/plain Regex Regex

Note: The custom content-type feature is not supported for the SOAP to REST transformed APIs.

Configure Custom Content-types

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

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

To configure custom content-type

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

  2. Select General > Custom Content-types.

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

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

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

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

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

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

Configuring API Callback Processor Settings

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

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

To configure API callback processor settings

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

  2. Select General > Callback processor settings.

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

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

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

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

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

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

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

  7. Click Save.

Tenant Management

Software AG provisions API Cloud in two different platforms based on your geographical location:

User Management

User Management in Integration Cloud

You can add and manage users and access profile information from the User Management page in Integration Cloud.

Users: User personas who can access API Gateway and perform tasks. There are two user personas, API Gateway Administrator and API Gateway Provider depending on the access profiles assigned to the users. An API Gateway provider can perform functions depending on the teams and access privileges assigned.

Access profiles: The functional privileges that are grouped together to form an access profile, and associate LDAP or local groups to the access profile. User can create an access profile, add functional privileges to the profile, associate groups to access profiles, and delete an access profile.

For information on managing users and access profiles, see webMethods Integration Cloud Help.

User Management in Software AG Cloud

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

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

Note: Only the Cloud-Tenant-Administrators can create and modify users.

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

Note: The APIGateway-User created in Software AG Cloud by Cloud-Tenant-Administrator are part of API-Gateway-Providers team in API Gateway. In API Gateway, the Cloud-Tenant-Administrator is known as API-Gateway-Administrator, who has necessary privileges to associate users to groups and teams from the User management section.

View User Details

You can view user details along with user groups.

To view user details

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

  2. Select Users.
    A list of users appears.

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

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

User Groups

API Gateway is shipped with the following predefined groups:

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

The table lists the privileges based on the user group.

Privileges API Gateway Administrator API Provider
Manage APIs Y Y
Manage aliases Y Y
Manage policy templates Y N
Activate/Deactivate APIs Y Y
Manage global policies Y N
Manage threat protection configurations Y N
Manage applications Y Y
Activate/Deactivate global policies Y N
Publish API to service registry Y Y
Manage packages and plans Y Y
Activate/Deactivate packages Y Y
Publish to API Portal Y Y
View administration configurations Y N
Execute service result cache APIs Y Y
Manage user administration Y N
Manage general administration configurations Y N
Manage destination configurations Y N
Manage promotions Y Y
Manage security configurations Y N
Manage system settings Y N
Manage service registeries Y N
Import assets Y Y
Export assets Y Y
Manage microgateways Y N
Manage Custom Dashboards Y N

Authentication and Authorization

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

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

Note: You cannot delete predefined users, groups, and teams but you can delete the groups and teams that are created in API Gateway.

Adding a Group

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

To add a group

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

  2. Select Groups.

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

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

    Field Description
    Name Name of the user group.
    Description A description for the user group.
  5. Click Save to save the group details at this stage and provide the group information for the user at a later time.

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

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

  8. Click Save.

Modifying a Group

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

To modify a group

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

  2. Click Groups.
    A list of groups appears.

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

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

  5. Modify the basic information of the user.

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

  7. Click Save.

Deleting a Group

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

To delete a group

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

  2. Click Groups.
    A list of groups appears.

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

    Note: You cannot delete predefined groups.

  4. Click Yes in the confirmation dialog.

API Gateway Functional Privileges

The following table lists the functional privileges and their description:

Functional Privilege Description
Select all To select all the listed functional controls.
Manage APIs To create and manage APIs.
Activate/ Deactivate APIs To activate, deactivate and manage APIs.
Manage applications To create and manage applications and register applications with the APIs. You cannot modify or delete an application if you are not the owner of the application.
Manage aliases To create and manage aliases.
Manage global policies To apply a global policy to all APIs or the selected set of APIs.
Activate/Deactivate global policies To activate, deactivate, and manage global policies.
Manage policy templates To apply one or more policy templates to an API.
Manage threat protection configurations To prevent malicious attacks on applications that typically involve large, recursive payloads, and SQL injections.
Publish API to service registry To publish and unpublish APIs to service registry.
Manage packages and plans To create packages and plans, associate a plan with a package, and associate APIs with a package. In addition, you can view the list of packages, package details, APIs, and plans associated with the package.
Activate/ Deactivate packages To activate, deactivate, and manage packages.
Publish to 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.

Team Support

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

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

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

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

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

When to use Team support?

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

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

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

What is a Team in API Gateway?

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

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

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

Without Team support With Teams support
All users can view all details for all assets. User can view only the assets that are assigned to the teams that they are a part of.
Users can add, modify, delete, activate and deactivate assets, publish and promote assets, export and import assets based on their functional privileges. Privileges are assigned through teams.
Users can perform actions based on their team’s functional privileges.

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

When not to use Team support?

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

Teams management using API Gateway

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

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

Teams - Asset Association

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

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

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

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

Enabling Team Support

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

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

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

To enable teams

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

  2. Select General > Extended settings.

  3. Click Show and hide keys.

    All configurable parameters appear.

  4. Select the enableTeamWork from the parameter list.

    The enableTeamWork field appears in the Extended Settingssection.

  5. Type true in the enableTeamWork field.

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

The feature is enabled.

Creating Teams

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

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

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

Before you begin

Ensure that you have:

To create teams

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

  2. Click Teams.

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

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

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

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

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

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

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

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

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

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

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

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

    In this use case, you need to assign all privileges required to manage the APIs and applications assigned to the team. So, all functional privileges under the APIs, Policies, and Applications section are selected.

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

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

  12. Click Save.
    The DevTeam is created and appears in the list of teams.



    You can now assign assets to the team.

How do I Assign Teams during Asset Creation?

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

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

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

Before you begin

Ensure that you have:

To assign teams during asset creation

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

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

  3. Click Import from an File.

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

  5. Provide DevAPI in the Name field.

  6. From the Team drop-down list, select the teams that you want to assign the asset to. For this use case, select the DevTeam.



    The assigned teams appear in the Team field of Basic Information section in the API details page. In this example, the DevAPI is assigned to DevTeam.

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

How do I Assign Teams Using Team Assignment Rule?

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

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

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

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

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

Before you begin

Ensure that you have:

To assign teams using team assignment rule

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

  2. Click Global team assignments.

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

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

  5. Click Continue to filters >.

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

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

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

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

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

    Field Description
    Attribute Specifies the asset attribute.

    Available attributes: Name, Description, Tags.

    The global team assignment rule supports only API level tags.

    If you select multiple asset types, the tag filter is applicable to the API type alone and is not applicable for the for other asset types during filter evaluation.
    Operator Comparison operator to validate the attribute against the given value.
    Available operators:

    • Equals. Checks if the specified asset attribute is equal to the given value.

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

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

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

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

  9. Click Continue to assign teams >.

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

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

  12. Click the toggle button, adjacent to the rule.



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

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

How do I Modify Teams Assigned to an API?

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

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

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

Before you begin

To modify the teams of an API

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

  2. Click APIs on the title navigation bar.

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

  4. Click change.

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

    The change approval process is initiated.

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

  6. An approval request is sent to the approver.

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

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

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

How do I Change the Ownership of Multiple Teams?

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

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

To change the ownership of multiple teams

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

    POST http://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.

Team Support Considerations

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

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

Visibility and Accessibility of Assets

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

Scenarios that you must consider when using Team support

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

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

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

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

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

Asset type Visibility Accessibility
APIs Users can view the names, details, and versions of the APIs associated with their teams. Users can access APIs based on functional privileges assigned to their teams.
Users can view the names of applications that are associated with the APIs assigned to their teams. Users can remove the applications that are visible (from the API).
Applications Users can view the names, descriptions, versions of the applications associated with their teams. Users can access applications based on functional privileges assigned to their teams.
Users can view the names of APIs that are associated with the applications assigned to their teams. Users can remove the APIs that are visible (from the application).
Packages and plans. Users can view the names and details of the packages and plans assigned to their teams. Users can access packages and plans based on functional privileges assigned to their teams.
Global search field When users search for an asset using a keyword, the search returns only the assets that are assigned to your teams. Users can access assets based on functional privileges assigned to their teams.
Aliases, Global Policies, Users, Groups, Teams, and Scopes All users can view these assets, even if they have read-only access to API Gateway. User can access the assets based on the privilege assigned to the individual users, irrespective of their teams.
Importing and Exporting of Teams and Assets

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

Promotion management

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

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

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

Scope mapping

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

Scope mappings are visible to all users

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

Global policies for APIs

Global policies are visible to all users

API mashup

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

API versioning

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

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

Scenarios where you cannot use Teams support

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

Scenario 1

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

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

This image describes the flow that you can achieve:

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

This image describes the flow that you cannot achieve:

Scenario 2

The functional privileges assigned to a team applies across all users towards all assets assigned to the team. You cannot assign different privileges to different assets. That is, if a user has certain functional privilege through one of their teams, and when the user is assigned to another team that does not have the particular functional privilege, the user will still have the functional privilege assigned through the first team.

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

This image explains the flow that cannot be achieved:

Destination Configuration

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

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

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

Configuring Events for API Gateway Destination

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

To configure events for API Gateway destination

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

  2. Select Destinations.

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

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

    The available event types are:

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

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

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

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

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

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

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

    • API management

    • Application management

    • Team management

    • Group management

    • Package management

    • Promotion management

    • Approval management

    • Alias management

    • Analytics management

    • Policy management

    • Plan management

    • User management

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

  8. Click Save.

Troubleshooting Tips: API Gateway Destination

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

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

Resolution:

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

A sample use case is as follows:

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

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

Configuring API Portal Destination

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

To configure API Portal destination

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

  2. Select Destinations.

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

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

    Field Description
    Name Name of the portal being configured.
    Version Version of the portal being configured.
  5. Provide the following information in the Portal configuration section for Gateway to send data to API Portal:

    Field Description
    Base URL URL of the API Portal instance in the format http://host:port.
    Tenant The tenant details of API Portal.

    By default, default tenant is considered if the tenant information is not provided.
    Username Username credential to access API Portal instance.
    Password Password credential to access API Portal instance.
  6. Provide the following information in the Gateway configuration section for API Portal to create applications, request or revoke access tokens, subscriptions, and so on:

    Field Description
    Base URL URL of the API Gateway instance. This is pre-populated.
    Note: When a load balancer URL is updated in API Gateway, the API Gateway base URL is be updated to same in this field.
    Username Username credential of the API Gateway Administrator to access API Gateway instance.
    Password Password credential to access API Gateway instance.
    Stage name Optional. The stage name of one of the stages in an API Gateway instance. The stage name included here is displayed in the API details, API tryout, Manage APIs, and Application details pages in the API Portal instance.
  7. Click Test to ensure the connection with the API Portal details is established. This connection with the given server is tested and a success message appears.

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

Configuring Events for API Portal Destination

Pre-requisites:

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

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

To configure events for API Portal destination

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

  2. Select Destinations.

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

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

    The available event types are:

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

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

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

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

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

  7. Click Save.

Post-requisites:

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

Configuring CentraSite Destination

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

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

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

To configure CentraSite destination

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

  2. Select Destinations.

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

    The Communication section displays the following information:

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

    The SNMP section displays the following information:

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

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

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

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

Configuring Events for CentraSite Destination

Pre-requisites:

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

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

To configure events for API Gateway destination

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

  2. Select Destinations.

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

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

    The available event types are:

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

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

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

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

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

  7. Click Save.

Post-requisites:

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

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

Configuring Elasticsearch Destination

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

To configure Elasticsearch destination

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

  2. Select Destinations.

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

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

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

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

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

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

Configuring Events for Elasticsearch Destination

Pre-requisites:

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

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

To configure Elasticsearch destination

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

  2. Select Destinations.

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

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

    The available event types are:

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

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

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

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

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

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

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

    • API management

    • Application management

    • Team management

    • Group management

    • Package management

    • Promotion management

    • Approval management

    • Alias management

    • Analytics management

    • Policy management

    • Plan management

    • User management

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

  8. Click Save.

Post-requisites:

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

Configuring Email Templates

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

To configure Email Templates

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

  2. Select Destinations.

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

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

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

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

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

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

    The transaction event parameters from the API Gateway Metrics and
    Event Notification engine are:
    Runtime_Policy: @policy_action_name
    API: @api_name
    Version : @version
    Operation or Resource_Name: @operation_resource_name
    Native endpoint: @native_endpoint
    Event generation time: @description
    Consumer_Name: @consumer_name
    Consumer_ID: @consumer_ID
    Status: @status
    Coorelation_ID:@correlationID
    Error origin: @errorOrigin

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

    The monitor event parameters from the API Gateway Metrics and
    Event Notification engine are:
    Runtime_Policy: @policy_action_name
    API: @api_name
    Version : @version
    Operation or Resource_Name: @operation_resource_name
    Native endpoint: @native_endpoint
    Action type: @actionType
    Attribute: @attribute
    Consumer_Name: @consumer_name
    Consumer_ID: @consumer_ID
    Alert Message: @alertMessage

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

  5. Click Save.

Custom Destination

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

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

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.

    Troubleshooting Tips: API Gateway - API Portal Integration

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

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

    Remove the obsolete reference as follows:

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

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

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

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

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

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

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


    I cannot publish an API to API Portal.

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

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



    I see stale applications in API Portal.

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

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

    Audit Logging

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

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

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

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

    Best Practices for API Gateway Audit Logging

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

    Configuring Audit Logs

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

    The following events are available for audit log reports:

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

    To configure audit logs

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

    2. Select Destinations.

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

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

    5. Click Save.

    Viewing Audit Logs

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

    To view audit logs

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

    2. Select Audit logs.

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

      • Last 2 days

      • Last 7 days

      • Last 30 days

      • Last 60 days

      • Last 90 days

      • Custom

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

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

    Filtering Audit Log Results

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

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

    To filter audit logs

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

    2. Provide the following:

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

      • Operator - Conditional operator applied for the filters.

      • Value - Search keywords for the given filters.

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

    Downloading Audit Logs

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

    To download audit logs

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

    2. Select Audit logs.

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

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

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

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

      API Gateway audit log are listed below.

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

    Configuring External Accounts

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

    Service Registry

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

    API Gateway uses service registries in the following ways:

    Service Registries supported by API Gateway

    API Gateway currently supports the following service registries:

    Adding a Service Registry

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

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

    To add and configure a service registry

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

    2. Click External accounts.

    3. Click Add service registry.

      Field Description
      Name Name used by API Gateway for the instance of service registry that you are adding.
      Description Description of the instance of service registry.
      Type Type of service registry. Available values are: SERVICE_CONSUL and EUREKA.
      Endpoint configuration
      Endpoint URI The base URI for the service registry. This should include the IP address or the FQDN and the port on which the service registry accepts requests.
      Service discovery path The relative path of the service registry discovery service. API Gateway appends this path (and the service ID) to the Endpoint URI to generate a service discovery request for the service registry.

      Note: A service registry discovery service returns the address (IP address or FQDN) of an application instance for the requested service ID.
      Service registration path The relative path of the service registry registration service. API Gateway appends this path (and the service ID) to the Endpoint URI to generate a service registration request for the service registry.

      Note: API Gateway uses this service to register (publish) a service with the service registry.
      Service de-registration path The relative path of the service registry de-registration service. API Gateway appends this path (and the service ID) to the Endpoint URI to generate a service de-registration request for the service registry.

      Note: API Gateway uses this service to de-register (unpublish) a service with the service registry.
      Connection timeout (seconds) Specifies the time (in seconds) after which a connection attempt times out while communicating with the service registry.

      The precedence of the Connection Timeout configuration is as follows:

      1. If you specify a value for the Connection timeout field in routing endpoint alias, then the Connection timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.

      2. If you specify a value 0 for the Connection timeout field in routing endpoint alias, then API Gateway uses the value specified in the Connection timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.

      3. If you specify a value 0 or do not specify a value for the Connection timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.connectionTimeout property.

      4. If you do not specify any value for pg.endpoint.connectionTimeout, then API Gateway uses the default value of 30 seconds.
      Read timeout (seconds) Specifies the time (in seconds) after which a socket read attempt times out while communicating with the service registry.

      The precedence of the Read Timeout configuration is as follows:

      1. If you specify a value for the Read timeout field in routing endpoint alias, then the Read timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.

      2. If you specify a value 0 for the Read timeout field in routing endpoint alias, then API Gateway uses the value specified in the Read Timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.

      3. If you specify a value 0 or do not specify a value for the Read timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.readTimeout property.

      4. If you do not specify any value for pg.endpoint.readTimeout, then API Gateway uses the default value of 30 seconds.
      SSL configuration
      Keystore alias List of keystores that are configured in API Gateway. This is used when the service registry is SSL enabled.

      Lists all available keystores.
      Key alias Lists all the private keys that are present in the selected keystore alias. This is used when the service registry is SSL enabled.
      Truststore alias A truststore contains the certificates that are trusted by API Gateway. If the service registry is SSL enabled its certificate should be added to the selected truststore.
      Basic authentication details
      Username

      The basic authentication user name.

      Password

      The basic authentication password.

      Other configuration
      Heartbeat interval (This setting is applicable only to Eureka service registries.) The interval at which the API Gateway sends a heartbeat message to the Eureka server to renew its leases. Eureka expects clients, such as API Gateway, to renew the lease by sending heartbeats as per the heartbeat interval configured in the Eureka server.
      Headers
      Key

      An HTTP header key that is included in all the HTTP requests sent to the service registry.

      Value

      A value for the given HTTP header key.

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

    Removing a Service Registry

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

    To remove a service registry

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

    2. Click Service Registries.

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

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

    Configuring an AWS Alias

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

    To configure an AWS alias

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

    2. Click External accounts > AWS configuration.

    3. Click Add new AWS account.

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

      a. Name: Provide the AWS alias name.

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

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

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

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

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

    Configuring Integration Server Instance for API Implementation

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

    To configure an Integration Server details

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

    2. Click External accounts.

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

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

    5. Provide the following details:

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

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

    7. Click Add. The server details are saved.

    Runtime Events and Metrics Data Model

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

    Events Description
    Lifecycle A Lifecycle event is generated each time the API Gateway instance is started or shut down.
    Error An Error event is generated each time an invocation of API results in an error.
    Policy Violation A Policy Violation event is generated each time an invocation of API violates a policy that was configured for the API.
    Transaction A Transaction event is generated each time an API is invoked (successfully or unsuccessfully).
    Monitor A Monitor event is generated when a configured SLA parameter, such as the average response time, fault count, availability, and so on, is breached for the API.

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

    Metric Reports on…
    Availability The percentage of time that an API was available during the current interval. A value of 100 indicates that the API was always available. Only the time when the API is unavailable counts against this metric. If invocations fail due to policy violations, this parameter could still be as high as 100.
    Average Response Time The average amount of time it took the API to complete all invocations in the current interval. This is measured from the moment API Gateway receives the request until the moment it returns the response to the client.
    Fault Count The number of failed invocations in the current interval.
    Maximum Response Time The maximum amount of time it took the API to complete an invocation in the current interval.
    Minimum Response Time The minimum amount of time it took the API to complete an invocation in the current interval.
    Successful Request Count The number of successful API invocations in the current interval.
    Total Request Count The total number of requests for each API running in API Gateway in the current interval.

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

    API Gateway

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

    Transactional Events

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI1
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationIp IP address of the application associated with the API invocation.
    Example:10.20.248.33
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationName Name of the application associated with the API invocation.
    An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    cachedResponse Indicates whether the response is sent to the client from the cached data present in API Gateway through the Service result caching policy or the response is received from Native service and sent to client.
    Possible values are: Cached, Not-Cached
    callbackRequest Indicates whether the event is generated for a callback request.
    Possible values are:
    • true. This denotes that the event is generated for a callback request.
    • false. This denotes that the event is generated for a normal response.
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    customFields The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    eventSource The source where the event occurred.
    Example: API_Gateway_Instance
    errorOrigin The origin of error.
    Example: Nativeservice
    eventType The type of event that occurred.
    Example: Transactional
    externalCalls List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]
    gatewayTime Duration in milliseconds, to process a request by API Gateway. This does not include native service processing duration.
    gatewayTime = totalTime - providerTime
    Example: 20
    httpMethod The HTTP method used to invoke the API.
    Example: GET
    messagePayload This is applicable only for WebSocket APIs. The message payload for a particular API invocation.
    Example: Sample WebSocket message
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    pacakgeId The unique identifier for the API package.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    packageName Name of the API package.
    Example: Travel Package
    planId The unique identifier for the API plan.
    Example: d0f84954-9732-11e5-b9f4-f159eafe47b2
    planName Name of the API plan.
    Example: Gold Plan
    providerTime Time in milliseconds required for API Gateway to invoke a native provider and receive a response. This time includes the overhead incurred by API Gateway. Overhead includes the time it takes for a provider to process a request and return a response, plus any network latency to or from the provider. Subtracting total time from provider time must give a rough indicator of the API Gateway overhead.
    Example: 20
    queryParameters This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    request The API request payload data.
    Example: <RequestPayload>
    requestHeaders Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    response The API request response data.
    Example: <ResponsePayload>
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    responseHeaders Response header in the outgoing response.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, POST, DELETE, PUT","Connection":"close","Date":"Fri, 30 Mar 2018 08:25:45 GMT","Access-Control-Allow-Headers":"Content-Type, api_key, Authorization","Content-Type":"application/xml"}
    nativeHttpMethod The HTTP method used to invoke the native service.
    Example: GET.
    nativeRequestHeaders Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899", "postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    nativeReqPayload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    nativeResponseHeaders Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    nativeResPayload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    nativeURL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.**
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1
    status Status of the API request.
    Possible values are: SUCCESS, FAILURE
    totalDataSize The total combined size of request and response payloads in bytes.
    Example: 100
    totalTime Time in milliseconds required to invoke the API provider. This time includes the overhead incurred by API Gateway. Overhead includes security overhead for encryption, decryption, and load-balance retries.
    Example: 120

    Error Events

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.20.248.33
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    errorDesc Message that describes the error that occurred.
    Example: Invocation for SampleAPI was rejected based on policy violation, response code: 503
    eventSource The source where the event occurred.
    Example: API_Gateway_Instance
    eventType The type of event that occurred.
    Example: Error Event
    httpMethod The HTTP method used to invoke the API.
    Example: GET
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.**
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1

    Monitoring Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: EnforcePolicy-HardLimit
    alertType The type of alert generated for the event.
    Possible values are: Monitor, sla
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.20.248.33
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventSource The source where the event occurred.
    Example: API_Gateway_Instance
    eventType The type of event that occurred.
    Example: Monitor Event
    httpMethod The HTTP method used to invoke the API.
    Example: GET
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.**

    Lifecycle Events

    Column Description
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: LifeCycle
    gatewayStatus Status of the API Gateway instance.
    Possible values are: STARTED or STOPPED
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.**

    Policy Violation Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: A violation was detected for policy (Unknown-Policyuser ): application could not be identified. Anonymous access is not allowed for this service!
    alertSource Name of the API Gateway policy that generated the alert message.
    Example: Unknown-Policy
    alertType The type of alert generated for the event.
    Example: PolicyViolation
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.20.248.33
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventSource The source where the event occurred.
    Example: API_Gateway_Instance
    eventType The type of event that occurred.
    Example: Policy Violation Event
    httpMethod The HTTP method used to request the API access.
    Example: GET
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.**
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1

    Performance Metrics

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    availability The percentage of time that an API was available during the current interval. A value of 100 indicates that the API was always available. If invocations fail due to policy violations, this parameter could still be as high as 100.
    Example: 100
    avgResponseTime The average amount of time it took the API to complete each invocation in the current interval. Response time is measured from the moment API Gateway receives the request until the moment it returns the response to the caller.
    Example: 135
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: Performance Metrics Event
    faultCount The number of failed API invocations in the current interval.
    Example: 10
    includeFaults Includes failed API invocations.
    Possible values are: true, false
    intervalStart The starting date and time from which you want to examine metrics.
    Example: 1526294632172
    intervalStop The ending date and time until which you want to examine metrics.
    Example: 1526294632182
    maxResponseTime The maximum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 343
    minResponseTime The minimum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 10
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    successCount The number of successful API invocations in the current interval.
    Example: 100
    totalCount The total number of API invocations (successful and unsuccessful) in the current interval.
    Example: 110

    Threat Protection Events

    Column Description
    alertAction A helpful action taken on the API for the alert.
    Example: DENY
    filterName Name of the threat protection filter.
    Example: DoSFilter
    message If the API invocation failed, message that describes the error that occurred.
    Example: Global Denial of Service limits were reached: Maximum requests limit of 2 in 120 seconds has been exceeded.
    requestHost Hostname of the machine from which the API access request was submitted.
    Example: 10.60.34.152
    requestTime Date and time the request was submitted.
    Example: 1501671101509
    requestType The type of request that was received for the API.
    Example: ALL
    requestUser Name of the user on API Gateway from whom the request is received.
    Example: null
    resourcePath The relative URI path of a resource that was used for API invocation.
    Example: invoke/pub.date/getCurrentDate
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    ruleName The API Gateway rule that triggered the event.
    Example: GlobalDoSRule
    serverHost The name or IP address of the machine on which the thread protection server is running.
    Example: 10.60.34.83
    serverPort The port number on which the thread protection server is configured to listen for incoming requests.
    Example: 8911
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.**

    API Portal

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

    Transactional Events

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    <Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    consumerId The unique identifier for the consumer associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    consumerIp IP address of the consumer associated with the API invocation.
    Example: 10.1.1.211
    consumerName Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a security policy that is configured for the API.
    Example: SampleApplication
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    customFields The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    errorOrigin The origin of error.
    Example: Nativeserivce
    eventType The type of event that occurred.
    Example: Transactional
    externalCalls List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":" These external calls can be to a native service or service registry. <br>Example:[{“externalCallType”:“SERVICE_REGISTRY_CALL”,“externalURL”:“http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": “200”},{“externalCallType”:“NATIVE_SERVICE_CALL”,“externalURL”:“https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]`
    messagePayload This is applicable only for WebSocket APIs. The message payload for a particular API invocation.
    Example: Sample WebSocket message
    operationName Name of the API operation that is invoked. Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    providerTime Time in milliseconds required for API Gateway to invoke a native provider and receive a response. This time includes the overhead incurred by API Gateway. Overhead includes the time it takes for a provider to process a request and return a response, plus any network latency to or from the provider. Subtracting total time from provider time must give a rough indicator of the API Gateway overhead.
    Example: 20
    queryParameters This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    request The API request payload data.
    Example: <RequestPayload>
    requestHeaders Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    response The API response payload data.
    Example: <ResponsePayload>
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    responseHeaders Response header in the outgoing response.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, POST, DELETE, PUT","Connection":"close","Date":"Fri, 30 Mar 2018 08:25:45 GMT","Access-Control-Allow-Headers":"Content-Type, api_key, Authorization","Content-Type":"application/xml"}
    nativeHttpMethod The HTTP method used to invoke the native service.
    Example: GET.
    nativeRequestHeaders Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899", "postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    nativeReqPayload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    nativeResponseHeaders Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    nativeResPayload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    nativeURL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1
    status Status of the API request.
    Possible values are: SUCCESS, FAILURE
    totalDataSize The total combined size of request and response payloads in bytes.
    Example: 100
    totalTime Time in milliseconds required to invoke the API provider. This time includes the overhead incurred by API Gateway. Overhead includes security overhead for encryption, decryption, and load-balance retries.
    Example: 120

    Error Events

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    consumerId The unique identifier for the consumer associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    consumerIp IP address of the consumer associated with the API invocation.
    Example: 10.20.248.33
    consumerName Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a security policy that is configured for the API.
    Example: SampleApplication
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    errorDesc Message that describes the error that occurred. Service invocation for SampleAPI was rejected based on policy violation, response code: 503
    eventType The type of event that occurred.
    Example: Error Event
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 503
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2

    Monitoring Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: EnforcePolicy-HardLimit
    alertType The type of alert generated for the event.
    Example: sla
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    consumerId The unique identifier for the consumer associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    consumerIp IP address of the consumer associated with the API invocation.
    Example: 10.20.248.33
    consumerName Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: Monitor Event
    httpMethod The HTTP method used to request the API access.
    Example: GET
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    responseCode The HTTP response status code that indicates success or failure of the requested operation. Example: 200
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2

    Lifecycle Events

    Column Description
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventStatus Status of the API Gateway instance.
    Possible values are: STARTED or STOPPED
    eventType The type of event that occurred.
    Example: LifeCycle
    targetName Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance

    Policy Violation Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: A violation was detected for policy (Unknown-Policyuser ): application could not be identified. Anonymous access is not allowed for this service!
    alertSource Name of the API Gateway policy that generated the alert message.
    Example: Unknown-Policy
    alertType The type of alert generated for the event.
    Example: PolicyViolation
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    consumerId The unique identifier for the consumer associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    consumerIp IP address of the consumer associated with the API invocation.
    Example: 10.20.248.33
    consumerName Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: Policy Violation Event
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2

    Performance Metrics

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    availability The percentage of time that an API was available during the current interval. A value of 100 indicates that the API was always available. If invocations fail due to policy violations, this parameter could still be as high as 100.
    Example: 100
    avgResponseTime The average amount of time it took the API to complete each invocation in the current interval. Response time is measured from the moment API Gateway receives the request until the moment it returns the response to the caller.
    Example: 135
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: Performance Metrics Event
    faultCount The number of failed API invocations in the current interval.
    Example: 10
    includeFaults Includes failed API invocations.
    Possible values are: true, false
    intervalStart The starting date and time from which you want to examine metrics.
    Example: 2015-08-26 04:13:35 PM
    intervalStop The ending date and time until which you want to examine metrics.
    Example: 2015-08-26 04:13:45 PM
    maxResponseTime The maximum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 343
    minResponseTime The minimum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 10
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    successCount The number of successful API invocations in the current interval.
    Example: 100
    totalCount The total number of API invocations (successful and unsuccessful) in the current interval.
    Example: 110

    Threat Protection Events

    Column Description
    alertAction A helpful action taken on the API for the alert.
    Example: DENY
    filterName Name of the threat protection filter.
    Example: DoSFilter
    message If the API invocation failed, message that describes the error that occurred.
    Example: Global Denial of Service limits were reached: Maximum requests limit of 2 in 120 seconds has been exceeded.
    requestHost Hostname of the machine from which the API access request was submitted.
    Example: 10.60.34.152
    requestTime Date and time the request was submitted.
    Example: 1501671101509
    requestType The type of request that was received for the API.
    Example: ALL
    requestUser Name of the user on API Gateway from whom the request is received.
    Example: null
    resourcePath The relative URI path for a resource that was used for API invocation.
    Example: invoke/pub.date/getCurrentDate
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    ruleName The API Gateway rule that triggered the event.
    Example: GlobalDoSRule
    serverHost The name or IP address of the machine on which the thread protection server is running.
    Example: 10.60.34.83
    serverPort The port number on which the thread protection server is configured to listen for incoming requests.
    Example: 8911

    Audit Log

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

    Transactional Events

    Column Description
    API_ID The unique identifier for the API.
    Example: ec1473cc-40a0-479e-9126-474a917c3c89
    API_NAME Name of the API in which the event occurred.
    Example: SampleAPI
    API_VERSION The system-assigned version identifier for the API.
    Example: 1.0
    AUDITTIMESTAMP Date and time when the event was written to the log.
    Example: 2017-08-07 07:22:22
    CONSUMER_IP IP address of the consumer associated with the API invocation.
    Example: 10.60.37.42
    CONSUMER_NAME Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a policy that is configured for the API.
    Example: SampleApplication
    CONTEXTID The unique identifier for the current context information API Gateway uses to connect related entries from different logs. This column is currently not used. It appears as NULL or as an empty string.
    Example: 81546147-41a8-4998-8150-02ba67bb08c2
    CORRELATIONID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    CUSTOMFIELDS The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    ERROR_ORIGIN The origin of error.
    Example: Nativeservice
    EVENT_PK The primary key (PK) that uniquely identifies the event that occurred.
    Example: 1
    EXTERNAL_CALLS List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]
    INSERTTIMESTAMP Date and time when the event was generated in API Gateway.
    Example: 2017-08-07 07:22:22
    MSGID The ID assigned to the message by the API provider. This column is currently not used.
    Example: 361dc2f8-a60b-fc21-8545-9b07fce1a479
    NATIVE_ENDPOINT The endpoint URL of the native API that is invoked.
    Example: http://petstore.swagger.io/v2/pet/55
    NATIVE_HTTP_METHOD The HTTP method used to invoke the native service.
    Example: GET.
    NATIVE_REQUEST_HEADERS Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899","postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    NATIVE_REQ_PAYLOAD The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    NATIVE_RESPONSE_HEADERS Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    NATIVE_RES_PAYLOAD The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    NATIVE_URL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    OPERATION_NAME Name of the API operation or resource that is invoked.
    Example: /pet/{petId}
    PROVIDER_TIME Time in milliseconds required for API Gateway to invoke a native provider and receive a response. This time includes the overhead incurred by API Gateway. Overhead includes the time it takes for a provider to process a request and return a response, plus any network latency to or from the provider. Subtracting total time from provider time must give a rough indicator of the API Gateway overhead.
    Example: 1336
    QUERY_PARAMETERS This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    REQUEST_HEADERS Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    RESPONSE_HEADERS Response header in the outgoing response.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, POST, DELETE, PUT","Connection":"close","Date":"Fri, 30 Mar 2018 08:25:45 GMT","Access-Control-Allow-Headers":"Content-Type, api_key, Authorization","Content-Type":"application/xml"}
    ROOTCONTEXTID The unique identifier for the root context information API Gateway uses to connect related entries from different logs. This column is currently not used. It appears as NULL or as an empty string.
    Example: 81546147-41a8-4998-8150-02ba67bb08c2
    SERVERID The API Gateway server on which the transaction event occurred. This column is currently not used. It appears as NULL or as an empty string.
    Example: *SampleHost:80
    SERVICE_NAME Name of the service in which the event occurred.
    Example: Swagger_Petstore
    SESSION_ID A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: 6dfcd849198c4a7e96b4ff89bc2deaf5
    SOURCE_GATEWAY_NODE Source API Gateway’s IP address.
    Example: 10.0.75.1
    STATUS Status of the API request.
    Possible values are: SUCCESS, FAILURE
    TOTAL_TIME Time in milliseconds required to invoke the API provider. This time includes the overhead incurred by API Gateway. Overhead includes security overhead for encryption, decryption, and load-balance retries.
    Example: 1042

    CentraSite

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

    Transactional Events

    Column Description
    ApiUserVersion The system-assigned version identifier for the API.
    Example: 1.0
    Consumer Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a policy that is configured for the API.
    Example: SampleApplication
    ConsumerId The unique identifier for the consumer associated with the API invocation.
    Example: be8b27d6-8f79-4c6e-b06c-a628d2ba30c3
    Consumer IP Address IP address of the consumer associated with the API invocation.
    Example: 10.60.20.169
    CorrelationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    Created Time Date and time when the event was generated in API Gateway.
    Example: 2017-08-09 01:27:45 AM
    CustomFields The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    ErrorOrigin The origin of error.
    Example: Nativeservice
    Event Type The type of event that occurred.
    Example: Transaction Event
    External Calls List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]
    Native HTTP Method The HTTP method used to invoke the native service.
    Example: GET.
    Native Request Headers Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899", "postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    Native Req Payload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    Native Response Headers Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    Native Res Payload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    Native URL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    PartnerId The unique identifier for the partner that generated the audit record.
    Example: unknown
    Provider Round Trip Time Time in milliseconds required for API Gateway to invoke a native provider and receive a response. This time includes the overhead incurred by API Gateway. Overhead includes the time it takes for a provider to process a request and return a response, plus any network latency to or from the provider. Subtracting total time from provider time must give a rough indicator of the API Gateway overhead.
    Example: 1700
    queryParameters This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    requestHeaders Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    RequestPayload The API request payload data.
    Example: <RequestPayload>
    responseHeaders Response header in the outgoing response.
    Example: `{“Server”:“Jetty(9.2.9.v20150224)”,“Access-Control-Allow-Origin”:”*“,“Access-Control-Allow-Methods”:“GET, POST, DELETE, PUT”,“Connection”:“close”,“Date”:“Fri, 30 Mar 2018 08:25:45 GMT”,“Access-Control-Allow-Headers”:“Content-Type, api_key, Authorization”,“Content-Type”
    ResponsePayload The API response payload data.
    Example: <ResponsePayload>
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1
    Total Round Trip time Time in milliseconds required to invoke the API provider. This time includes the overhead incurred by API Gateway. Overhead includes security overhead for encryption, decryption, and load-balance retries.
    Example: 1707
    Gateway Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance
    Request Status Status of the API request. Possible values are: SUCCESS, FAILURE

    Error Events

    Column Description
    ApiUserVersion The system-assigned version identifier for the API.
    Example: 1.0
    Consumer Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a policy that is configured for the API.
    Example: SampleApplication
    ConsumerId The unique identifier for the consumer associated with the API invocation.
    Example: be8b27d6-8f79-4c6e-b06c-a628d2ba30c3
    Consumer IP Address IP address of the consumer associated with the API invocation.
    Example: 10.60.20.169
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    Created Time Date and time when the event was generated in API Gateway.
    Example: 2017-08-09 08:24:04 AM
    Error Source The source where the error occurred.
    Example: e1cc3c7b-495d-11e7-a5a6-88cf17308ba4
    Error Description Message that describes the error that occurred.
    Example: Resource / not found
    Event Type The type of event that occurred.
    Example: Error Event
    Gateway Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance

    Monitoring Events

    Column Description
    ApiUserVersion The system-assigned version identifier for the API.
    Example: 1.0
    Alert Source Name of the API Gateway policy that generated the alert message.
    Example: Monitorpolicy, EnforcePolicy-HardLimit
    Alert Type The type of alert generated for the event.
    Possible values are: Monitor, Sla
    Alert Description Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: MSLA_ALERT MESSAGE
    Consumer Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a policy that is configured for the API.
    Example: SUCRQ_App
    ConsumerId The unique identifier for the consumer associated with the API invocation.
    Example: d0e2e008-1890-4f2c-8a91-7678cb92dbfb
    Consumer IP Address IP address of the consumer associated with the API invocation.
    Example: 10.60.37.118
    Created Time Date and time when the event was generated in API Gateway.
    Example: 2017-08-08 02:27:34 PM
    Event Type The type of event that occurred.
    Example: Monitoring Event
    Error Description Message that describes the error that occurred.
    Example: Resource / not found
    Gateway Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance
    Monitored Attribute The monitored attribute which has breached the configured SLA.
    Example: AVGRESPONSETIME GT 1.0, SUCCESSCOUNT EQ 3, REQUESTCOUNT GT 10

    Policy Violation Events

    Column Description
    ApiUserVersion The system-assigned version identifier for the API.
    Example: 1.0
    Alert Source Name of the API Gateway policy that generated the alert message.
    Example: Unknown-Policy
    Alert Type The type of alert generated for the event.
    Example: PolicyViolation
    Alert Description Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: A violation of policy was detected : Unable to identify the application for the request
    Consumer Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a policy that is configured for the API.
    Example: unknown
    ConsumerId The unique identifier for the consumer associated with the API invocation.
    Example: unknown
    Consumer IP Address IP address of the consumer associated with the API invocation.
    Example: 10.60.37.118
    Created Time Date and time when the event was generated in API Gateway.
    Example: 2017-08-09 08:25:52 AM
    Event Type The type of event that occurred.
    Example: Policy Violation Event
    Gateway Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance

    Lifecycle Events

    Column Description
    TimeStamp Date and time when the event was generated in API Gateway.
    Example: 2017-08-26 04:13:35 PM
    Target Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance
    LifeCycleStatus Status of the API Gateway instance.
    Possible values are: STARTED or STOPPED
    LifeCycleAlertDescription The alert notification message for the lifecycle event.
    Example: Alert_Message

    Elasticsearch

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

    Transactional Events

    Column Description
    apiId The unique identifier for the API.
    Example: af70b2de-c9c5-4f40-94be-7d8622743e42
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.60.37.42
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    cachedResponse Indicates whether the response is sent to the client from the cached data present in API Gateway through the Service result caching policy or the response is received from Native service and sent to client.
    Possible values are: Cached, Not-Cached
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    isCallbackRequest Indicates whether the event is generated for a callback request.
    Possible values are:
    • true. This denotes that the event is generated for a callback request.
    • false. This denotes that the event is generated for a normal response.
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    customFields The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    errorOrigin The origin of error.
    Example: Nativeservice
    eventType The type of event that occurred.
    Example: Transactional
    externalCalls List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]
    httpMethod The HTTP method used to invoke the API.
    Example: GET
    messageType This is applicable only for WebSocket APIs. This indicates the type of a WebSocket message.
    Possible values are: binary, text
    nativeHttpMethod The HTTP method used to invoke the native service.
    Example: GET.
    nativeRequestHeaders Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899", "postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    nativeReqPayload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    nativeResponseHeaders Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    nativeResPayload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    nativeURL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    operationName Name of the API operation that is invoked.
    Example: /pet/{petId}
    packageId The unique identifier for the API package.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    packageName Name of the API package.
    Example: Travel Package
    planId The unique identifier for the API plan.
    Example: d0f84954-9732-11e5-b9f4-f159eafe47b2
    planName Name of the API plan.
    Example: Gold Plan
    providerTime Time in milliseconds required for API Gateway to invoke a native provider and receive a response. This time includes the overhead incurred by API Gateway. Overhead includes the time it takes for a provider to process a request and return a response, plus any network latency to or from the provider. Subtracting total time from provider time must give a rough indicator of the API Gateway overhead.
    Example: 1367
    queryParameteres This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    reqPayload The API request payload data.
    Example: <RequestPayload>
    requestHeaders Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    resPayload The API response payload data.
    Example: <ResponsePayload>
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 404
    responseHeaders Response header in the outgoing response.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, POST, DELETE, PUT","Connection":"close","Date":"Fri, 30 Mar 2018 08:25:45 GMT","Access-Control-Allow-Headers":"Content-Type, api_key, Authorization","Content-Type":"application/xml"}
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1
    status Status of the API request.
    Possible values are: SUCCESS, FAILURE
    totalDataSize The total combined size of request and response payloads in bytes.
    Example: 51
    totalTime Time in milliseconds required to invoke the API provider. This time includes the overhead incurred by API Gateway. Overhead includes security overhead for encryption, decryption, and load-balance retries.
    Example: 1401

    Error Events

    Column Description
    apiId The unique identifier for the API.
    Example: af70b2de-c9c5-4f40-94be-7d8622743e42
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.60.37.42
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    errorDesc Message that describes the error that occurred.
    Example: Native service provider error. Code : 404
    eventSource The source where the event occurred.
    Example: API_Gateway_Instance
    eventType The type of event that occurred.
    Example: Error
    httpMethod The HTTP method used to invoke the API.
    Example: GET
    operationName Name of the API operation that is invoked.
    Example: /pet/{petId}
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 404

    Monitoring Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: EnforcePolicy-HardLimit
    alertSource Name of the API Gateway policy that generated the alert message.
    Example: Monitorpolicy
    alertType The type of alert generated for the event.
    Example: Monitor
    apiId The unique identifier for the API.
    Example: af70b2de-c9c5-4f40-94be-7d8622743e42
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.60.37.42
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventSource The source where the event occurred.
    Example: API_Gateway_Instance
    eventType The type of event that occurred.
    Example: Monitor
    httpMethod The HTTP method used to request the API access.
    Example: GET
    monitorAttr The monitored attribute which has breached the configured SLA.
    Example: AVGRESPONSETIME GT 1.0, SUCCESSCOUNT EQ 3, REQUESTCOUNT GT 10
    operationName Name of the API operation that is invoked.
    Example: /pet/{petId}
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200

    Policy Violation Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: A violation was detected for policy (Unknown-Policyuser ): application could not be identified. Anonymous access is not allowed for this service!
    alertSource Name of the API Gateway policy that generated the alert message.
    Example: Unknown-Policy
    alertType The type of alert generated for the event.
    Example: PolicyViolation
    apiId The unique identifier for the API.
    Example: af70b2de-c9c5-4f40-94be-7d8622743e42
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: 9434e90d-65c3-4e37-8ccb-595b8df3e645
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.60.37.42
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventSource The source where the event occurred.
    Example: API_Gateway_Instance
    eventType The type of event that occurred.
    Example: PolicyViolation
    httpMethod The HTTP method used to request the API access.
    Example: GET
    operationName Name of the API operation that is invoked.
    Example: /pet/{petId}
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 503

    Performance Metrics

    Column Description
    apiId The unique identifier for the API.
    Example: af70b2de-c9c5-4f40-94be-7d8622743e42
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    availability The percentage of time that an API was available during the current interval. A value of 100 indicates that the API was always available. If invocations fail due to policy violations, this parameter could still be as high as 100.
    Example: 100.0
    avgResponseTime The average amount of time it took the API to complete each invocation in the current interval. Response time is measured from the moment API Gateway receives the request until the moment it returns the response to the caller.
    Example: 1376
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: PerformanceData
    faultCount The number of failed API invocations in the current interval.
    Example: 1
    includeFaults Includes failed API invocations.
    Possible values are: true, false
    intervalStart The starting date and time from which you want to examine metrics.
    Example: 02 Aug 2017 10:51:31 GMT
    intervalStop The ending date and time until which you want to examine metrics.
    Example: 02 Aug 2017 10:52:31 GMT
    maxResponseTime The maximum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 1401
    minResponseTime The minimum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 1352
    operationName Name of the API operation that is invoked.
    Example: /pet/{petId}
    successCount The number of successful API invocations in the current interval.
    Example: 1
    totalCount The total number of API invocations (successful and unsuccessful) in the current interval.
    Example: 2

    Email

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

    Transactional Events

    Column Description
    API Name of the API in which the event occurred.
    Example: SampleAPI
    CorrelationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    CustomFields The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    Description Message that describes the date and time the API was invoked and the application associated with the API invocation. Invoked at 4/24/18 1:50 PM Consumer Name: Unknown Consumer ID: Unknown
    ErrorOrigin The origin of error.
    Example: Nativeservice
    External Calls List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]
    Native Endpoint The endpoint URL of the native API being invoked.
    Example: http://petstore.swagger.io/v2/pet/55
    Native HTTP Method The HTTP method used to invoke the native service.
    Example: GET.
    Native Request Headers Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899", "postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    Native Req Payload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    Native Response Headers Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    Native Res Payload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    Native URL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    Operation/Resource Name Name of the operation or resource that is being invoked on the API.
    Example: /pet/{petId}
    QueryParameters This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    RequestHeaders Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    ResponseHeaders Response header in the outgoing response.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, POST, DELETE, PUT","Connection":"close","Date":"Fri, 30 Mar 2018 08:25:45 GMT","Access-Control-Allow-Headers":"Content-Type, api_key, Authorization","Content-Type":"application/xml"}
    Runtime Policy Name of the runtime policy that is enforced on the API.
    Example: Log Invocation
    Source Gateway Node Source API Gateway’s IP address.
    Example: 10.0.75.1
    Status Status of the API invocation.
    Possible values are: SUCCESS, FAILURE
    Version The system-assigned version identifier for the API.
    Example: 1.0

    Monitoring Events

    Column Description
    API Name of the API in which the event occurred.
    Example: SampleAPI
    Action Type The type of alert generated for the event.
    Example: Monitor
    Alert Message Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: Test
    Attribute The monitored attribute which has breached the configured SLA.
    Example: AVGRESPONSETIME GT 1.0, SUCCESSCOUNT EQ 3, REQUESTCOUNT GT 10
    Consumer ID The unique identifier for the consumer associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    Consumer Name Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a policy that is configured for the API.
    Example: SampleApplication
    Native Endpoint The endpoint URL of the native API that is being invoked.
    Example: http://petstore.swagger.io/v2/pet/55
    Operation/Resource Name Name of the operation or resource that is being invoked on the API.
    Example: /pet/{petId}
    Runtime Policy Name of the runtime policy that is enforced on the API.
    Example: Log Invocation
    Version The system-assigned version identifier for the API.
    Example: 1.0

    Local Log

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

    Transactional Events

    Column Description
    API Name of the API in which the event occurred.
    Example: SampleAPI
    API Version The system-assigned version identifier for the API.
    Example: 1.0.0
    Application ID The unique identifier for the application associated with the API invocation.
    Example: 7908eb44-d107-4670-929d-89111fc9347c
    Application IP Address IP address of the application associated with the API invocation.
    Example: 10.60.37.42
    Application Name Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    Correlation ID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    customFields The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    Error Origin The origin of error.
    Example: Nativeservice
    External Calls List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]
    Invoked at Date and time the API is invoked.
    Example: Invoked at 5/14/18 6:56 PM
    Native HTTP Method The HTTP method used to invoke the native service.
    Example: GET.
    Native Request Headers Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899", "postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    Native Req Payload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    Native Response Headers Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    Native Res Payload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    Native URL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    Operation/Resource name Name of the API operation or resource that is invoked.
    Example: /pet
    Partner ID The unique identifier for the partner that generated the audit record.
    Example: unknown
    QueryParameters This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    RequestHeaders Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    ResponseHeaders Response header in the outgoing response.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, POST, DELETE, PUT","Connection":"close","Date":"Fri, 30 Mar 2018 08:25:45 GMT","Access-Control-Allow-Headers":"Content-Type, api_key, Authorization","Content-Type":"application/xml"}
    Runtime Policy Name of the API Gateway policy that triggered the event.
    Example: Log Invocation
    Session Id A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: 81439d366e874bc79d9f81490e30e6e0
    Source Gateway Node Source API Gateway’s IP address.
    Example: 10.0.75.1
    Status Status of the API request.
    Possible values are: SUCCESS, FAILURE
    Target endpoint The endpoint URL of the native API that is invoked.
    Example: http://petstore.swagger.io/v2/pet/55

    Monitoring Events

    Column Description
    Application ID The unique identifier for the application associated with the API invocation.
    Example: 7908eb44-d107-4670-929d-89111fc9347c
    Application IP IP address of the application associated with the API invocation.
    Example: 10.60.37.42
    Breached attribute The monitored attribute which has breached the configured SLA.
    Example: AVGRESPONSETIME GT 1.0, SUCCESSCOUNT EQ 3, REQUESTCOUNT EQ 1
    Description Message that describes the event that occurred.
    Example: Alert_Message
    Name Name of the application associated with the API invocation. An application name is populated as Unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: Unknown
    Native Endpoint The endpoint URL of the native API that is invoked.
    Example: http://petstore.swagger.io/v2/pet/55
    Operation/Resource name Name of the API operation or resource that is invoked.
    Example: /pet
    Policy name Name of the API Gateway policy that triggered the event.
    Example: Monitor Policy