Webmethod API

webMethods API Cloud: API Gateway User's Guide
Version 10.3
October 2018
This document applies to webMethods API Cloud: API Gateway Version 10.3 and to all subsequent releases.
Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.
Copyright © 2016-2018 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or
its affiliates and/or their licensors.
The name Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG and/or
Software AG USA Inc. and/or its subsidiaries and/or its affiliates and/or their licensors. Other company and product names mentioned
herein may be trademarks of their respective owners.
Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at
hp://softwareag.com/licenses.
Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product
documentation, located at hp://softwareag.com/licenses and/or in the root installation directory of the licensed product(s).
This software may include portions of third-party products. For third-party copyright notices, license terms, additional rights or
restrictions, please refer to "License Texts, Copyright Notices and Disclaimers of Third Party Products". For certain specific third-party
license restrictions, please refer to section E of the Legal Notices available under "License Terms and Conditions for Use of Software AG
Products / Copyright and Trademark Notices of Software AG Products". These documents are part of the product documentation, located
at hp://softwareag.com/licenses and/or in the root installation directory of the licensed product(s).
Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with
Software AG.
Document ID: YAIC-UG-103-20190111

M
Table of Contents
Table of Contents
About this Guide............................................................................................................................11

Document Conventions............................................................................................................ 11
Online Information and Support............................................................................................... 12
Data Protection......................................................................................................................... 13
webMethods API Gateway............................................................................................................ 15

Introduction to webMethods API Gateway............................................................................... 16
Searching Data in API Gateway.............................................................................................. 17
Using Help in API Gateway......................................................................................................19
API Gateway Administration.........................................................................................................21

Overview of Administration Tasks............................................................................................ 22
General Configuration...............................................................................................................22
Configuring Extended Settings..........................................................................................22
Configuring API Fault Settings.......................................................................................... 33
Approval Configuration...................................................................................................... 34
Configuring Approvals for Creating an Application.................................................... 35
Configuring Approvals for Registering Application.....................................................37
Configuring Approvals for Updating Application.........................................................39
Configuring Approvals for Subscribing Package........................................................42
Managing Pending Requests..................................................................................... 44
Deleting Requests............................................................................................... 46
URL Aliases.......................................................................................................................46
Creating URL Alias.....................................................................................................47
Using Port Mappings with URL Alias..................................................................48
Adding Port Mapping to URL Alias.....................................................................48
Deleting Port Mapping for URL Alias..................................................................49
Enabling Partial Matching of URL Aliases................................................................. 49
Modifying a URL Alias............................................................................................... 50
Deleting a URL Alias..................................................................................................50
Example: Usage Scenarios of URL Aliases...............................................................50
Custom Content-types.......................................................................................................52
Configure Custom Content-types............................................................................... 53
Configuring API Callback Processor Settings................................................................... 54
Transaction Alerts..............................................................................................................55
Configuring Criteria for a Transaction Alert Notification Across Stages..................... 55
Modifying Transaction Alert Configurations................................................................57
Deleting a Transaction Alert Configuration................................................................ 58
Security Configuration.............................................................................................................. 58
Keystore and Truststore.................................................................................................... 58
Configuring Keystore Information...............................................................................59
webMethods API Cloud: API Gateway User's Guide Version 10.3 3

M
Table of Contents
Configuring Truststore Information.............................................................................60

Configuring Keystore and Truststore Information...................................................... 61
Modifying Keystore Information..................................................................................62
Deleting Keystore Information....................................................................................63
Modifying Truststore Information................................................................................63
Deleting Truststore Information.................................................................................. 64
SAML Issuer...................................................................................................................... 64
Custom Assertions............................................................................................................ 68
Creating a Custom Assertion..................................................................................... 70
Viewing Custom Assertion List and Assertion Configuration..................................... 72
Modifying Custom Assertion...................................................................................... 72
Deleting Custom Assertion.........................................................................................73
Example: Custom Assertions..................................................................................... 73
Kerberos Settings.............................................................................................................. 77
Configuring API Gateway to Use Kerberos............................................................... 78
OAuth, JWT, and OpenID Configuration........................................................................... 79
OAuth Authentication Use case and Workflow.......................................................... 79
JWT Authentication Use case and Workflow.............................................................85
OpenID Authentication Use case and Workflow........................................................ 88
Configuring the Internal Authorization Server............................................................ 92
Adding a Provider.......................................................................................................94
Adding an External Authorization Server................................................................... 97
Mapping OAuth or OpenID Scopes......................................................................... 102
Viewing Scope Mapping Details...............................................................................103
Viewing Provider List and Provider Configuration....................................................103
Modifying the Provider Configuration....................................................................... 104
Viewing Authorization Server List and Server Configuration....................................104
Modifying Authorization Server Configuration..........................................................105
Deleting an Authorization Server............................................................................. 105
Deleting a Provider...................................................................................................106
Destination Configuration........................................................................................................106
Configuring Events for API Gateway Destination............................................................107
Configuring API Portal Destination..................................................................................108
Configuring Events for API Portal Destination................................................................ 109
Configuring CentraSite Destination................................................................................. 110
Configuring Events for CentraSite Destination................................................................112
Configuring Elasticsearch Destination.............................................................................113
Configuring Events for Elasticsearch Destination........................................................... 114
Configuring Email Destination......................................................................................... 115
Configuring Email Templates....................................................................................117
Audit Logging..........................................................................................................................118
Configuring Audit Logs.................................................................................................... 120
Viewing Audit Logs..........................................................................................................121
Downloading Audit Logs..................................................................................................122
Service Registries...................................................................................................................123

M
Table of Contents
Adding a Service Registry...............................................................................................124

Removing a Service Registry..........................................................................................126
Users and Access Profiles......................................................................................................... 129

Manage Users and Access profiles........................................................................................130
APIs............................................................................................................................................... 131
Overview................................................................................................................................. 132
Creating an API by Importing an API from a File.................................................................. 135
Creating an API by Importing an API from a URL................................................................. 135
Creating an API from Scratch................................................................................................ 136
Overview of Creating a REST API from Scratch............................................................ 136
Creating a REST API...................................................................................................... 142
API Mashups.......................................................................................................................... 153
Creating an API Mashup.................................................................................................157
Viewing API List and API Details........................................................................................... 160
REST API Details............................................................................................................ 160
SOAP API Details............................................................................................................162
OData API Details........................................................................................................... 163
Filtering APIs.......................................................................................................................... 166
Activating an API.................................................................................................................... 166
Deactivating an API................................................................................................................167
Publishing APIs.......................................................................................................................167
Publishing APIs to API Portal......................................................................................... 167
Publishing a Single API to API Portal......................................................................168
Publishing Multiple APIs to API Portal in a Single Operation...................................169
Publishing APIs to Service Registries.............................................................................170
Publishing a Single API to Service Registries......................................................... 171
Publishing Multiple APIs to Service Registries in a Single Operation...................... 172
Unpublishing APIs.................................................................................................................. 172
Unpublishing APIs from API Portal................................................................................. 172
Unpublishing a Single API from API Portal..............................................................172
Unpublishing Multiple APIs from API Portal in a Single Operation.......................... 173
Unpublishing APIs from a Service Registry.................................................................... 174
Unpublishing a Single API from Service Registries................................................. 175
Unpublishing Multiple APIs from Service Registries in a Single Operation.............. 175
Modifying API Details............................................................................................................. 176
Updating APIs.........................................................................................................................177
Updating an API by Importing an API from a File...........................................................178
Updating an API by Importing an API from a URL......................................................... 179
API Mocking............................................................................................................................181
Enabling API Mocking..................................................................................................... 182
Modifying API Mocking Details........................................................................................182
Custom Replacer.............................................................................................................185
Attaching Documents to an API............................................................................................. 185
SOAP to REST Transformation..............................................................................................187

M
Table of Contents
Activating SOAP to Rest Transformation........................................................................ 187

Modifying the REST Definitions for SOAP Operations....................................................188
Supported Content-types and Accept Headers...............................................................191
REST API Endpoints....................................................................................................... 192
Samples for REST Request............................................................................................ 192
Limitations........................................................................................................................195
Versioning APIs...................................................................................................................... 195
Creating New API Version...............................................................................................195
API Scopes............................................................................................................................. 196
Creating an API Scope................................................................................................... 196
Viewing List of API Scopes and Scope Details.............................................................. 198
Modifying API Scope Details...........................................................................................198
Deleting an API Scope....................................................................................................199
Example: Usage Scenarios of API Scopes.....................................................................200
Exposing a REST API to Applications................................................................................... 205
Exposing a SOAP API to Applications...................................................................................206
API Grouping.......................................................................................................................... 207
API Tagging............................................................................................................................ 207
Adding Tags to an API.................................................................................................... 208
Exporting APIs........................................................................................................................ 209
Exporting Specifications..........................................................................................................210
Deleting APIs.......................................................................................................................... 211
Deleting a Single API...................................................................................................... 211
Deleting Multiple APIs in a Single Operation.................................................................. 211
Example: Managing an API....................................................................................................212
Policies..........................................................................................................................................225
Overview................................................................................................................................. 226
Policy Validation and Dependencies...................................................................................... 228
Managing Threat Protection Policies......................................................................................236
Configuring Global Denial of Service Policy................................................................... 236
Configuring Denial of Service by IP Policy..................................................................... 238
Managing Denied IP List.................................................................................................239
Configuring Rules............................................................................................................ 239
Registering a Mobile Device or Application.................................................................... 245
Configuring Alert Settings................................................................................................246
System-defined Stages and Policies......................................................................................246
Transport..........................................................................................................................247
Enable HTTP/HTTPS............................................................................................... 247
Set Media Type........................................................................................................ 248
Identify and Access......................................................................................................... 248
Inbound Authentication - Message.......................................................................... 249
Identify and Authorize Application............................................................................253
Request Processing.........................................................................................................259
Invoke webMethods IS.............................................................................................259

M
Table of Contents
Request Transformation........................................................................................... 262

Validate API Specification........................................................................................ 269
Data Masking........................................................................................................... 273
Routing.............................................................................................................................276
Content-based Routing.............................................................................................276
Context-based Routing.............................................................................................282
Dynamic Routing...................................................................................................... 288
Load Balancer Routing.............................................................................................292
Straight Through Routing......................................................................................... 295
Custom HTTP Header..............................................................................................297
Outbound Authentication - Transport....................................................................... 297
Outbound Authentication - Message........................................................................301
Traffic Monitoring............................................................................................................. 303
Log Invocation.......................................................................................................... 303
Monitor Service Performance...................................................................................306
Monitor Service Level Agreement............................................................................308
Throttling Traffic Optimization...................................................................................312
Service Result Cache...............................................................................................314
Response Processing......................................................................................................316
Invoke webMethods IS.............................................................................................317
Response Transformation........................................................................................ 319
Validate API Specification........................................................................................ 325
Data Masking........................................................................................................... 328
CORS....................................................................................................................... 331
Error Handling................................................................................................................. 332
Conditional Error Processing....................................................................................332
Data Masking........................................................................................................... 337
The API for Context Variables.........................................................................................339
Managing Global Policies....................................................................................................... 354
Creating a Global Policy................................................................................................. 356
Modifying the Scope of a Global Policy.......................................................................... 357
Refining the Scope of a Global Policy............................................................................ 358
Associating Policies to a Global Policy........................................................................... 361
Configuring Properties for a Global Policy......................................................................362
Viewing List of Global Policies and Policy Details.......................................................... 363
Modifying Global Policy Details.......................................................................................364
Activating a Global Policy............................................................................................... 365
Deactivating a Global Policy........................................................................................... 366
Deleting a Global Policy..................................................................................................367
Copying a Global Policy..................................................................................................368
Exporting Global Policies................................................................................................ 369
Managing API-level Policies................................................................................................... 369
Assigning a Policy to an API...........................................................................................370
Viewing API Policy Details.............................................................................................. 370
Modifying API Policy Details........................................................................................... 371

M
Table of Contents
Managing Scope-level Policies...............................................................................................372

Creating a Scope-level Policy......................................................................................... 373
Viewing List of Scope-level Policies and Policy Details.................................................. 374
Modifying Scope-level Policy Details.............................................................................. 375
Deleting a Scope-level Policy..........................................................................................376
Managing Policy Templates....................................................................................................376
Creating a Policy Template............................................................................................. 377
Associating Policies with a Policy Template....................................................................377
Configuring Properties for a Policy Template..................................................................379
Viewing List of Policy Templates and Template Details.................................................. 380
Modifying Policy Template Details...................................................................................381
Deleting a Policy Template..............................................................................................381
Copying a Policy Template..............................................................................................382
Applying a Policy Template on the API Details Page..................................................... 383
Modifying a Policy Template on the API Details Page....................................................384
Saving Policy Definition of an API as Policy Template................................................... 385
Supported Alias and Policy Combinations............................................................................. 386
Aliases...........................................................................................................................................391
Overview................................................................................................................................. 392
Creating a Simple Alias..........................................................................................................392
Creating an Endpoint Alias.....................................................................................................393
Creating an HTTP Transport Security Alias........................................................................... 394
Creating a SOAP Message Security Alias............................................................................. 398
Creating a webMethods Integration Server Service Alias......................................................402
Creating an XSLT Transformation Alias................................................................................. 403
Applications..................................................................................................................................405
Overview................................................................................................................................. 406
Creating an Application.......................................................................................................... 407
Viewing List of Applications and Application Details.............................................................. 415
Regenerating API Access Key............................................................................................... 415
Modifying Application Details..................................................................................................416
Registering an API with Consumer Applications from API Details Page................................416
Registering APIs with Consumer Applications from Application Details Page....................... 417
Suspending an Application..................................................................................................... 418
Activating a Suspended Application....................................................................................... 418
API Packages and Plans.............................................................................................................419

Overview................................................................................................................................. 420
Creating a Package................................................................................................................420
Creating a Plan.......................................................................................................................421
Viewing List of Packages and Package Details..................................................................... 424
Modifying a Package.............................................................................................................. 425
Deleting a Package................................................................................................................ 426
Activating a Package..............................................................................................................426

M
Table of Contents
Publishing a Package.............................................................................................................427
Viewing List of Plans and Plan Details.................................................................................. 427
Modifying a Plan.....................................................................................................................428
Deleting a Plan....................................................................................................................... 429
Import Archives............................................................................................................................431
Importing Exported Files.........................................................................................................432
Asset Promotions........................................................................................................................ 435

Manage Stages, Promotions, and Rollbacks......................................................................... 436
Stages..............................................................................................................................437
Adding a Stage.........................................................................................................437
Viewing Stage List and Stage Details......................................................................439
Modifying Stage Details........................................................................................... 439
Deleting a Stage.......................................................................................................440
Promotions.......................................................................................................................440
Promoting Assets..................................................................................................... 440
Viewing Promotion List and Promotion Details........................................................ 443
Repromoting Assets................................................................................................. 444
Rollbacks......................................................................................................................... 445
Rollback Asset Promotions...................................................................................... 445
Viewing Rollback List and Rollback Details............................................................. 446
API Gateway Analytics................................................................................................................447

Analytics Dashboards............................................................................................................. 448
API Gateway Dashboard.................................................................................................449
API-specific Dashboard................................................................................................... 454
Viewing API Usage Report.....................................................................................................456
Downloading API Usage Report.............................................................................................457
Runtime Events and Metrics Data Model...............................................................................458
API Gateway....................................................................................................................459
API Portal........................................................................................................................ 472
Audit Log......................................................................................................................... 484
CentraSite........................................................................................................................ 487
Elasticsearch....................................................................................................................493
Email................................................................................................................................ 502
Local Log......................................................................................................................... 504

M
Even Header

M
Odd Header
About this Guide
This guide describes how you can use API Gateway and other API Gateway components
to effectively manage APIs for services that you want to expose to applications, whether
inside your organization or outside to partners and third parties.
To use this guide effectively, you should have an understanding of the APIs that you
want to expose to the developer community and the access privileges you want to
impose on those APIs.
Document Conventions
Convention Description
Bold Identifies elements on a screen.
Narrowfont Identifies service names and locations in the format

folder.subfolder.service , APIs, Java classes, methods, properties.
Italic Identifies:
Variables for which you must supply values specific to your own
situation or environment.
New terms the first time they occur in the text.
References to other documentation sources.
Monospace Identifies:
font
Text you must type in.
Messages displayed by the system.
Program code.
{} Indicates a set of choices from which you must choose one. Type
only the information inside the curly braces. Do not type the { }
symbols.
| Separates two mutually exclusive choices in a syntax line. Type

one of these choices. Do not type the | symbol.
[] Indicates one or more options. Type only the information inside

the square brackets. Do not type the [ ] symbols.

M
Even Header
Convention Description
... Indicates that you can type multiple options of the same type.
Type only the information. Do not type the ellipsis (...).
Online Information and Support

Software AG Documentation Website
You can find documentation on the Software AG Documentation website at “hp://
documentation.softwareag.com”. The site requires credentials for Software AG's Product
Support site Empower. If you do not have Empower credentials, you must use the
TECHcommunity website.
Software AG Empower Product Support Website

If you do not yet have an account for Empower, send an email to
“empower@softwareag.com” with your name, company, and company email address
and request an account.
Once you have an account, you can open Support Incidents online via the eService
section of Empower at “hps://empower.softwareag.com/”.
You can find product information on the Software AG Empower Product Support
website at “hps://empower.softwareag.com”.
To submit feature/enhancement requests, get information about product availability,
and download products, go to “Products”.
To get information about fixes and to read early warnings, technical papers, and
knowledge base articles, go to the “Knowledge Center”.
If you have any questions, you can find a local or toll-free number for your country
in our Global Support Contact Directory at “hps://empower.softwareag.com/
public_directory.asp” and give us a call.
Software AG TECHcommunity
You can find documentation and other technical information on the Software AG
TECHcommunity website at “hp://techcommunity.softwareag.com”. You can:
Access product documentation, if you have TECHcommunity credentials. If you do
not, you will need to register and specify "Documentation" as an area of interest.
Access articles, code samples, demos, and tutorials.
Use the online discussion forums, moderated by Software AG professionals, to
ask questions, discuss best practices, and learn how other customers are using
Software AG technology.
Link to external websites that discuss open standards and web technology.

M
Odd Header
Data Protection
Software AG products provide functionality with respect to processing of personal data
according to the EU General Data Protection Regulation (GDPR). Where applicable,
appropriate steps are documented in the respective administration documentation.

M
Even Header

M
Odd Header
webMethods API Gateway
1 webMethods API Gateway

■ Introduction to webMethods API Gateway ................................................................................... 16
■ Searching Data in API Gateway .................................................................................................. 17
■ Using Help in API Gateway ......................................................................................................... 19

M
Even Header
Introduction to webMethods API Gateway

webMethods API Gateway enables an organization to securely expose APIs to external
developers, partners, and other consumers for use in building their own applications on
their desired platforms. It provides a dedicated, web-based user interface to perform all
the administration and API related tasks such as creating APIs, defining and activating
policies, creating applications, and consuming APIs. API Gateway gives you rich
dashboard capabilities for API Analytics. APIs created in API Gateway can also be
published to API Portal for external facing developers' consumption. webMethods API
Gateway supports REST-based APIs and SOAP-based APIs, provides protection from
malicious aacks, provides a complete run-time governance of APIs, and information
about gateway-specific events and API-specific events.
Note: Software AG recommends using API Gateway user interface for all the
functionalities provided by API Gateway and not use the Integration Server
user interface.
API Gateway provides the following key features:

Support for SOAP APIs, and REST APIs
API Gateway supports REST-based APIs and SOAP-based APIs. This support enables
organizations to leverage their current investments in SOAP-based APIs while adopting
REST for new APIs. The API Gateway's SOAP to REST transformation feature enables
an API provider to expose parts of the SOAP API or expose the complete SOAP API
with RESTful interface. API Gateway allows you to customize the way the SOAP
operations are exposed as REST resources.
Secure APIs
API Gateway protects APIs from malicious aacks initiated by external client
applications. Administrators can secure traffic between API consumer requests and
the execution of services on API Gateway by filtering requests coming from particular
IP addresses and blacklisting specified IP addresses, detecting and filtering requests
coming from particular mobile devices. You can avoid additional inbound firewall holes
when the native APIs are hosted on webMethods ESB.
Policy enforcement
API Gateway provides complete run-time governance of APIs. API Gateway enforces
access tokens such as API key check, OAuth2 token and operational policies such as
security policies for run-time requests between applications and native services. API
providers can enforce security, traffic management, monitoring, and SLA management
policies, can transform requests and responses into expected formats. and collect events
metrics on API consumption and policy evaluation. API Policies can be defined globally
and applied to a set of APIs. With API Gateway you can also define policy templates that
can be applied across APIs.
Mediation

M
Odd Header
API Gateway provides routing policies such as content-based, and context-based, for
run-time requests between applications and native services. These policies perform
routing and load balancing of incoming requests to an API.
Message transformation
API Gateway lets you configure an API and to transform the request and response
messages to suit your requirements. To do this, you can specify an XSLT file to
transform messages during the mediation process. You can also configure an API
to invoke Integration Server services to pre-process and post-process the request or
response messages. You can use only the pre-shipped Integration Server services.
Easy discovery and testing of APIs
API Gateway provides filter capabilities to quickly find APIs of interest. API
descriptions and additional documentation, usage examples, and information about
policies enforced at the API level provide more details to the developers that help them
decide whether to adopt a particular API. Developers can use the provided samples and
expected error and return codes to see how the API works.
Clustering support
Multiple instances of API Gateway can be clustered together to provide scalability and
high availability.
Built-in usage analytics
API Gateway provides information about Gateway-specific events and API-specific
events, details about which APIs are more popular than others. The Gateway-specific
events information is available by way of dashboards to users. With this information,
providers can understand how their APIs are being used, which in turn can help identify
ways of improving their users' experience and increase API adoption.
Packages and Plans
API Gateway provides capabilities to create and manage packages and plans. This helps
the API providers in providing tiered access to their APIs to allow different service
levels and pricing plans. Users can view the details of the package, such as included
APIs and associated plans. Plans provide information about pricing and quality of
service terms defined within them. Consumers can subscribe to any plan available under
the package, based on their business needs.
API Mashups
API Gateway allows you to consolidate services and expose them as a single service.
You can create API mashups that extend an API operation by grouping it with other API
operations available in API Gateway.
Searching Data in API Gateway

The search feature in API Gateway is a type-ahead search; a simple and easy to use
search facility where you can type the text of interest to search. You can search for all

M
Even Header
items that contain one or more specified keywords (that is, text strings) in the item's
properties. Some of the properties are name, description, version, key, value, and so on
in the API.
You can search for the following types of data:
APIs
Applications
Alias
Plans
Packages
To search for an item, type a string in the search box in the title navigation bar. A list of
search result is displayed directly below the Search box. The number of matches found
are displayed in five sections depending on the type they fit in: APIs, Application, Alias,
Packages, and Plans. A minimum of five search results are displayed in each category. If
there are no results as per the search string typed, a message displays saying so.
If you find what you are searching for in the search result box, click on it to view
the details. You are navigated to the specific page that displays more information.
For example, if you are searching for an API and click the displayed result, you are
navigated to the specified API details page. If you are searching for an application and
click the displayed result, you are navigated to the specified Application details page
If you want to see all the search results click Show all results in the search result box. The
Advanced search page is displayed. This is a dedicated page that displays extensive
search results. In the Advanced search page, you can search or filter the results in the
following ways: by type or keyword.
By type: Select one or more types in the left navigation pane to see search results
pertaining to the selected types. For example, if you select the type APIs, all the APIs
that have the specified string is displayed.
By keyword: Type a keyword in the Search by keyword field, all the search results
containing the specified keyword are displayed in the list. For example, if you type
the keyword petstore, all search results containing the petstore would be filtered
and displayed.
Note: You cannot search for REST resources and methods in a REST API. The
search function only works for the name and description of the REST API. For
example, you can search for a REST API named LibraryAPI. But you cannot
search for a REST resource named book or a REST method POST within the
REST API. However, the search function works for name, description, and
operations of SOAP APIs.
You cannot search for resources and methods of an OData API.

M
Odd Header
Using Help in API Gateway

API Gateway's built-in context-sensitive help gives an overview of the functionality of
API Gateway.
You can access API Gateway Help link by expanding the menu options icon , in the
title bar and selecting Help. This opens the introduction to the webMethods API Gateway
page in the help system. You can browse the required topics in the navigation pane.
Click on a topic to display the detailed information. You will also find the help links in
the form of a help icon on several pages of the API Gateway user interface. Click the
help icon on the page to view the corresponding detailed information.

M
Even Header

M
Odd Header
API Gateway Administration
2 API Gateway Administration

■ Overview of Administration Tasks ................................................................................................ 22
■ General Configuration .................................................................................................................. 22
■ Security Configuration .................................................................................................................. 58
■ Destination Configuration ........................................................................................................... 106
■ Audit Logging ............................................................................................................................. 118
■ Service Registries ...................................................................................................................... 123

M
Even Header
Overview of Administration Tasks

Various aspects of the way API Gateway functions can be configured:
General configuration: extended seings, service faults, approval seings, URL
aliases, custom content-types, callback processor seings and transaction alert
configuration.
Security configuration: keystores and trustore, SAML issuer, custom assertions,
Kerberos seings, OAuth 2.0, JWT, and OpenID provider.
Destination configuration: targets to which the events and performance metrics data
is sent.
Service registries: add and configure service registries.
General Configuration
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 seings which are advanced parameters required for your
server to operate properly.
Configure API fault seings for errors being returned by the API Gateway to the
applications.
Configure approval seings.
Configure URL aliases.
Configure the custom content-types.
Configure API callback request seings.
Configure transaction alerts seings.
Configuring Extended Settings

You must have the API Gateway's manage user administration functional privilege
assigned to configure the extended seings.
You can configure advanced parameter seings in the Extended seings section. These
parameters affect the operation of your server. You must not change these seings
unless requested to do so by Software AG Global Support. You can configure the wa
parameter seings in this section.

M
Odd Header
To configure the extended settings

1. Expand the menu options icon , in the title bar, and select Administration.
2. Select General > Extended settings.
3. Click Show and hide keys. This displays all the configurable parameters.
4. You can configure any of the following parameters in the Extended keys section by
providing the required values. The configured values are listed under Extended
seings at the top of the page.
Parameter and Description
allowExceedMaxWindowSize
Provide the value true to exceed the maximum window size configured and
false to avoid exceeding the maximum window size.
The default value is true.
apiDocumentsRestrictedExtension
Specify a list of restricted file extensions to prevent users from uploading
files with those extensions as the input document to 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
apiDocumentsUploadSizeLimitInMB
Provide a value (in MB) to restrict the size of the document that can be
uploaded as the input document to API. It is important to set this to a
reasonable limit, but not too large to avoid uploading files that are too large
and can slow down the system.
Default value is 5.
apig_MENConfiguration_tickInterval

M
Even Header
Provide a value to specify the time interval (in seconds) between each interval
processor iteration. This must be an evenly divisible fraction of the smallest
policy interval, which is one minute.
Default value is 15.
If you have configured the result window size in elastic search, specify the
configured value to fetch results accordingly.
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 groups that the APIs would be grouped under.
The default groups provided are Finance Banking and Insurance,Sales
and Ordering,Search,Transportation and Warehousing
You can delete or add new groups that the APIs can be grouped under.
apiKeyExpirationPeriod
Specifies the length of time that the API key is valid. The key expires after
the set number of minutes, hours, days, months, or years. If a value is not
specified, then the API key never expires. 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 current
time of the application in the system + The value specified in the
apiKeyExpirationPeriod parameter.

M
Odd Header
apiKeyHeader
Provide the header value from which API Gateway receives the API key.
The default value is x-Gateway-APIKey
apiMaturityStatePossibleValues
Specify the API maturity state values that can be set for an API.
The default values provided are Beta, Deprecated, Experimental,
Production, Test.
decodeAllDelimitersInURI
When set to false the URI in the request is not decoded.
When set to trueit overrides the limiters and decodes the complete path to
get a meaningful URI.
defaultEncoding
Specify the default encoding format.
The default value is UTF-8.
enableHotdeploy
This parameter is used to enable hot deploy function in API Gateway.
The default value is true, which means the hot deployment functionality is
enabled.
You can change the value to false if you want to disable hot deployment.
Note: Enabling or disabling hot deploy requires a browser refresh to reflect

the changed UI behavior to ongoing user sessions.
esScrollTimeout
Provide a value that specifies the time out interval for fetching the result that
is greater than maxWindowSize.
Default value is the time, in milliseconds, required to fetch the records
specified in maxWindowSize.
events.collectionPool.maxThreads

M
Even Header
Provide a value that specifies the maximum number of threads to be used for
event data collection. This value must be greater than or equal to the value of
events.CollectionPool.minThreads.
Default value is 8.
events.collectionPool.minThreads
Provide a value that specifies the minimum number of threads to be used for
event data collection. Specifying more threads means that API Gateway can
collect more data faster, but it increases the usage of system resources, which
could result in slower service execution.
Default value is 1.
events.collectionQueue.size
Provide a value that specifies the size of the collection work queue to be
used during event data collection. This queue is used only when there are
not enough collection pool threads to process all the data. For example, if
event.CollectionPool.maxThreads is set to 10 and the 10 threads are not
sufficient for processing all the data, then the unprocessed data is put into the
collection work queue. If the queue capacity is reached, then any additional
data is lost.
Default value is 10000 items of data allowed in the queue.
Specifying a large queue and a small collection pool minimizes CPU usage
and operating system resources, but this can lead to low throughput which
causes delays in data collection. Using a small collection work queue
generally requires larger collection pool sizes, which keeps CPUs busier.
This avoids the delay but may encounter unacceptable scheduling overhead,
which also decreases service execution.
events.reportingPool.maxThreads
Provide a value that specifies the maximum number of threads to be used for
event data reporting. This value must be greater than or equal to the value of
events.ReportingPool.minThreads.
Default value is 4.
events.reportingPool.minThreads
Provide a value that specifies the minimum number of threads to be used
for event data reporting. Specifying more threads means that API Gateway
can send more events to the event destination faster, but it also increases the
usage of system resources, which could result in slower service execution.

M
Odd Header
Default value is 2.
events.reportingQueue.size
Provide a value that specifies the size of the reporting work queue to be
used during event data reporting. This queue is used only when there are
not enough reporting pool threads to process all the data to be reported. For
example, if events.ReportingPool.maxThreads is set to 10, and the 10
threads are not sufficient for processing all the data, then the unprocessed
data is put into the reporting work queue. If the queue capacity is reached,
then any additional data is lost.
Default value is 5000 items of data allowed in the queue.
Specifying a large queue and a small reporting pool minimizes CPU usage
and operating system resources, but this can lead to low throughput which
causes delays in data reporting. Using a small reporting work queue
generally requires larger reporting pool sizes, which keeps CPUs busier.
This avoids the delay but may encounter unacceptable scheduling overhead,
which also decreases service execution
forwardInternalAPIsRequest
This parameter is required in the case of a paired gateway deployment
scenario using an Advanced Edition license at DMZ.
Provide the value true to forward the incoming requests to internal APIs that
are deployed in the green zone.
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
maxAllowedZipFileSize
Provide a value to specify the maximum zip file size allowed.
maxWindowSize

M
Even Header
Provide a value to set the result window size that specifies the number of
records per query.
Default value is 10000.
pg_Active_OpenID_Provider
Specifies the unique identifier (ID) of an active OpenID Provider.
pg_JWT_isHTTPS
Provide a value to specify the transport protocol over which the JSON Web
Tokens (JWTs) are granted authorization.
Available values are:
true. Sets the transport protocol HTTPS. This is set by default.
false. Sets the transport protocol HTTP.
pg_oauth2_isHTTPS
Provide a value to specify the transport protocol over which the OAuth 2.0
access tokens are granted authorization.
pg_OpenID_isHTTPS
Provide a value to specify the transport protocol over which the OpenID (ID)
tokens are granted authorization.
pg_xslt_disableDoctypeDeclarations
Disables the xslt doc type declarations.
pg_xslt_enableDOM
Provide the value true to enable DOM parsing.

M
Odd Header
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.
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.
pg.cs.snmpTarget.retries
Specify the number of times to resend SNMP traps upon failure.
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

M
Even Header

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
pg.lb.failoverOnDowntimeErrorOnly
Specify API Gateway's behavior for load-balanced endpoints. The default
value is true, which means that API Gateway fails over only if the service
fault is a downtime error. If the parameter is set to false, then in a load-
balanced routing scenario, if a service fault is encountered in the response
coming from endpoint 1, then API Gateway immediately tries the next
configured endpoint. There is no distinction on the type of fault present in
the response from endpoint 1.
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.
pg.snmp.communityTarget.maxRequestSize
Specifies the maximum size (in bytes) for SNMP traps.
pg.snmp.communityTarget.retries
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

M
Odd Header

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
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.
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.
pg.snmp.userTarget.retries
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.

M
Even Header
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.
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
pg.uddiClient.publish.maxThreads
Specify the maximum allowed number of threads to publish the performance
metrics data to CentraSite.
pg.uddiClient.uddiClientTimeout
Specify the number of milliseconds that can elapse before not publishing
performance metrics to an unavailable API Gateway instance.
pgmen.quotaSurvival.addLostIntervals
Specifies if 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.
saveAuditlogsWithPayload
Specifies whether the audit logs have to be saved along with payload.

M
Odd Header
The default value is true, which specifies that the audit logs have to saved
with payload.
The value false specifies that audit logs are not saved with payload.
sendClientRequestURI
Decodes the URI that comes in a request to API Gateway without changing
the path of the URL before sending it out to the native service.
When the value is set to true the URI is sent as is without decoding. It
encodes the unicode character contained in the request.
setDefaultContentType
Specifies that default content type is set.
The default value is true
transformerPoolSize
Provide the transformer pool size.
5. You can configure the wa parameters in the Wa keys section by providing the
required values.
The configured wa keys are listed under Wa seings below the Extended keys at
the top of the page.
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 seings.
You can configure global error responses for all APIs to display the default error
message.
To configure the service fault settings

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.

M
Even Header
If you do not select this option then API Gateway sends the default error message.
4. Specify the error message text in the Default error message text box that is sent out
when the Send native provider fault is not selected.
5. Click Save.
Approval Configuration
API Gateway allows you to configure an approval process to ensure that the requests are
valid. If the requests are invalid, API Gateway enables approvers to reject the requests.
API Gateway allows you to configure approvals for:
Create application: To enforce approvals for creating an application in API Gateway.
Register application: To enforce approvals for associating an application with APIs.
Update application: To enforce approvals for modifying an application.
Subscribe package: To enforce approvals in API Gateway to enable API Portal
consumers for subscribing a package to a plan in API Portal.
In API Gateway, you can create an application and associate (register) the application
created with APIs. If you have the API Gateway's manage general administration
configurations functional privilege assigned, you can configure approvals for creating
or registering an application. If you have configured approvers, and if a user wants to
create and register an application in API Gateway, then the application is created and
registered with an API only if any one approver from the approvers group approves
the create application and the register application requests. Similarly, you can configure
approvals for updating an application or subscribing a package.
You can configure a set of different approvers for creating or registering applications.
For example, if you have configured an approvers group, group1 to approve or reject
a create application request and an approvers group, group2 to approve or reject a
register application request, then when a user creates and registers an application in API
Gateway, then the create application request must be approved by any one approver in
group1 . When the application is created, the register application request is sent to the
approvers in group2 and this register application request must be approved by any one
approver in group2 . When the request is approved, the application created is registered
to an API. However, if any one user from group2 rejects the request, then the application
gets created but is not register to an API.
API Gateway approvals can also be used when API Gateway is integrated with 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.

M
Odd Header
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 an Application

You have to configure the approval seings, to enforce approval for creating an
application in API Gateway.
To configure approvals for creating an application

2. Select General > Approval configuration > Create application.
3. Set the Enable toggle buon 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 associated with the approvers access profile 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 Administrators access profile, then the user
can approve or reject a pending request even if the user is not associated
with the Approvers group.
6. 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.
7. 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.

M
Even Header
Field Description
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.
8. 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.
9. 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.

email content.

For example, Approval of @event.type appears as
Approval of Create Application in the email sent,
where Create Application is the event.type.
10. Select Configure rejection mail template to be sent to requester.

request for creating an application is rejected.
11. Provide the following information in the Configure rejection mail template to be sent to
requester section:

M
Odd Header
Field Description

request for creating an application is rejected by the
approver.

email content.

Approval of Create Application in the email sent,
where Create Application is the event.type.
12. Click Cancel to revert to the last saved changes or to abandon all the changes if the
values are not saved.
13. Click Save.
Configuring Approvals for Registering Application

You have to configure the approval seings, 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

2. Select General > Approval configuration > Register application.
take effect.
5. Select the anyone from the Approved by drop-down list.

M
Even Header
This is to configure the email template to be sent to the approver for associating an
application with APIs.
to be sent to approve section:
Field Description

the request for associating an application with APIs.

email content.

approvers login ID.

request for associating an application with APIs is approved.
Field Description

request for associating an application with APIs is
approved by the approver.

email content.


M
Odd Header
Field Description
Approval of Register Application in the email sent,
where Register Application is the event.type.

request for registering an application is rejected.
requester section:
Field Description

request for associating an application with APIs is
rejected by the approver.

email content.

Approval of Register Application in the email sent,
where Register Application is the event.type.
13. Click Save.
Configuring Approvals for Updating Application

You have to configure the approval seings, to enforce approval for modifying an
existing application in API Gateway.
To configure approvals for updating an application

2. Select General > Approval configuration > Update application.
take effect.

M
Even Header


This is to configure the email template to be sent to the approver for approving the
request of modifying an existing application.
to be sent to approver section:
Field Description

the request for modifying an existing application.

email content.

approvers login ID.

request for modifying an existing application is approved.

M
Odd Header
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.

email content.

Approval of Update Application in the email sent,
where Update Application is the event.type.

request for modifying an existing application is rejected.
requester section:
Field Description

request for modifying an existing application is rejected
by the approver.

email content.

Approval of Update Application in the email sent,
where Update Application is the event.type.
13. Click Save.

M
Even Header
Configuring Approvals for Subscribing Package

You have to configure the approval seings in API Gateway, to enforce approval for
subscribing a package to a plan in API Portal.
To configure approvals for subscribing a package

2. Select General > Approval configuration > Subscribe package.
take effect.

This is to configure the email template to be sent to the approver for subscribing a
package.
to be sent to approve section:
Field Description

the request for subscribing a package.

email content.

approvers login ID.

M
Odd Header

request for subscribing a package is approved.
Field Description

request for subscribing a package is approved by the
approver.

email content.

Approval of Subscribe Package in the email sent,
where Subscribe Package is the event.type.

request for subscribing a package is rejected.
requester section:
Field Description

request for registering an application is rejected by the
approver.

email content.


M
Even Header
Field Description
Approval of Subscribe Package in the email sent,
where Subscribe Package is the event.type.
13. Click Save.
Managing Pending 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.
To approve or reject a pending request

1. Expand the menu options icon , in the title bar, and select Pending Requests.
The Pending requests page appears.
2. Select Pending Requests.
A list of pending requests appears with the following information:
Field Description
Requested by The name of the requestor.
Requestor The additional information or comments added by the

comments requestor.
Event The type of event for which the request is pending.

The options are:
Create application
Register application
Update application
Subscribe package
Request details The details of the type of event requested.

The details available for the following event types are:
Create application
Application name. The name of the application.

M
Odd Header
Field Description
Owner. The owner of the application.

Identifiers. Identifiers by which messages from a
particular consumer application is recognized at
run time.
Contact emails. The email address of the owner of
the application.
Version: The version of the application.
Register application
API. The API to which the application is
associated.
Update application
Owner. The owner of the application.
particular consumer application is recognized at
run time.
the application.
Version: The version of the application.
Subscribe package:
Application name. The name of the subscription.
Owner. The owner of the subscription.
particular consumer subscription is recognized at
run time.
the subscription.
Version. The version of the subscription.
Plan name. The name of the plan.
Package name. The name of the API package.
3. Click the Approve or Reject icon to approve or reject requests.

M
Even Header
Alternatively, you can select multiple pending requests to be approved or rejected

simultaneously by selecting the check boxes adjacent to the names of the requests.
The request gets removed from the Pending requests page.
Deleting Requests
When you perform a task, for example, you create an application in API Gateway, then
an approval request is generated if an approval is configured in API Gateway and this
request that is waiting for approvers approval is listed in the Pending Request section. If
you want to delete this request, you can delete it from the Pending Request section.
To delete a request
1. Expand the menu options icon , in the title bar, and select Pending Requests.
2. Select My requests.
A list of requests appears with the detailed information of the request.
3. Click the Delete icon for the request that has to be deleted.
4. Click Yes in the confirmation dialog.
URL Aliases
A URL alias is an alias that you create to replace a portion of the URL to an API on API
Gateway. The URL alias typically replaces the path portion of the URL which identifies
the name and invocation endpoint of the API. For example, if the URL is http://
test:2225/gateway/RESTCalcService/1.0, you can create a URL alias, calc for an
API, then the name and invocation endpoint of the API on API Gateway is replaced with
calc, for example, http://test:2225/calc. If the client sends a request that contains
the matching alias, then the corresponding URL path is invoked.
In addition to associating a URL alias with a single resource, you can also map different
resources for each port, therefore, based on the incoming port, the corresponding
resource path is invoked. This makes it possible to define a single URL alias that resolves
to different destinations based on the incoming port of the HTTP request.
URL aliases have several benefits:
A URL alias may be easier to type than full URL path names.
A URL alias is more secure than URL path names.
The URL aliases page displays a list of available URL aliases with the corresponding
details including the default URL path, port it is mapped to, and so on. You must have
the Manage aliases functional privilege assigned to manage the alias information.
Note: Any modifications to the URL aliases in Integration Server do not reflect in
API Gateway. Hence, Software AG recommends that you do not modify the
aliases through Integration Server Administrator. On migration from 10.0 to
10.1, the existing configuration in 10.0 is migrated to the API Gateway UI.

M
Odd Header
API Gateway only supports modification of URL aliases for the

WmAPIGateway package. To modify URL aliases for any other packages, you
must use Integration Server Administrator.
Creating URL Alias

When you create a URL alias, you create an association between an alias and an API on
API Gateway.
Keep the following information in mind when creating a URL alias:
An alias name must be unique across API Gateway.
You can associate a single URL alias with multiple resources by specifying port
mappings. A port mapping correlates the alias with a different URL alias based on
the port on which th request was received.
If you want to use URL alias with a REST resource you must enable partial matching
of URL aliases.
If you enabled or intend to enable partial matching of URL aliases, do not define an
alias that begins with another alias.
To create a URL alias

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://
Port number The port number to use when accessing the API.
When API Gateway receives a request that contains a URL
alias,API Gateway resolves the request destination by first
determining if there is a URL path associated with the
incoming port. If there is no URL path mapped to the port
number, then API Gatewayuses the default URL path for

M
Even Header
Field Description
the alias as the request destination. The port mappings are
always evaluated first.
Because the URL path can be different for each port, using
port mappings allows the use of a single URL alias with
multiple destinations. Each port can have only one URL
path mapping. You can add port mappings to multiple
destinations by clicking the +Add buon.
URL path The URL path for the URL alias and for port number
mapped for the URL alias.
The URL path cannot include a space or the following
characters: # % ? ’ “ < \
Default URL The URL path to the API on API Gateway.

path
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.
Using Port Mappings with URL Alias

For a URL alias, you can create one or more port mappings which associates a port with
a resource. Port mappings allow the use of a single URL alias with multiple resource
paths, because each port can be mapped to a different URL path.
When API Gateway receives a request that contains a URL alias,API Gateway resolves
the request destination by first determining if there is a URL path associated with the
incoming port. If there is no URL path mapped to the port number, then API Gateway
uses the default URL path for the alias as the request destination. The port mappings are
always evaluated first.
Adding Port Mapping to URL Alias

You can create multiple port mappings for a URL alias. Incoming requests with the URL
alias received on a port that has no URL path mapping, resolves to the path specified
in the Default URL Path field. If the alias does not specify a Default URL Path value, API
Gateway uses the alias as the URL path.
To add a port mapping to a URL alias


M
Odd Header

3. In the URL alias list, select the URL alias for which you want to define port
mappings.
4. In the Port number list, select the port for which you want to specify an alternate path.
5. In the URL path field, specify the path to API. The URL path cannot include a space or
the following characters: # % ? ’ “ < \
6. Click +Add to add the port mapping to the alias.
7. Click Save.
Deleting Port Mapping for URL Alias

You can delete any of the port mappings added to a URL alias.
Note: If you intend to delete all of the port mappings for a URL alias, make sure the
URL alias specifies a Default URL Path value.
To delete a port mapping for a URL alias

3. In the URL alias list, select the URL alias for which you want to delete a port
mapping.
4. In the Port number list, click in the action column of the port mapping that you
want to delete.
5. Repeat the preceding step for each port mapping that you want to delete for an alias.
6. 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

M
Even Header
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 Integration
Server (in the Integration Server Administrator, go to Settings > Extended link). The
default is false. For more information on configuring partial matching of URL aliases
using Integration Server, see webMethods Integration Server Administrator’s Guide.
Important: If you change the seing of this parameter, you must restart Integration
Server for the changes to take effect.
Modifying a URL Alias

To modify a URL alias
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

To delete a URL alias
3. In the URL Alias list, locate the row that contains the alias you want to delete, and
click .
4. Click Yes in the confirmation dialog box.
Example: Usage Scenarios of URL Aliases

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

M
Odd Header
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:
hps://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:
3. Click Add URL alias and provide the following values:
Field Value
Alias calc
Default URL gateway/RESTCalcService/1.0/postCalc

path
4. Click Save.
Suppose, the URL alias name provided while creating a URL alias is calc. You can now
expose the hps://test:5555/calc invocation endpoint to the API consumer instead of
hps://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,
hp://test:2225/calc
Additionally, you can use port mapping, if you want to use the same alias for a different
resource path. This can be done by providing a different resource path for each port,
instead of the default URL path in alias configuration. To use the same alias for a
different resource path:

M
Even Header

3. Click Add URL alias and provide the following values:
Field Value
Alias calc
Port number 5555
URL path gateway/RESTCalcService/1.0/postCalc
4. Click +Add to add port mappings to multiple destinations and provide the following
values:
Field Value
Port number 4000
URL path gateway/RESTCalcService/1.0/deleteCalc
5. Click Save.
Note: As the Default URL path is not provided, the incoming call for ports other
than 4000 and 5555 fails. If the Default URL path is provided then the port
mapping takes the first precedence. If the value of the port does not match,
then the Default URL path is used.
For the alias calc, each port is mapped to a different resource, for the invocation
endpoint:
hps://test03:4000/calc: RESTCalcService/1.0/deleteCalc resource is invoked.
hps://test03:4010/calc: error appears as the default URL is not provided and a path
is not configured for the 4010 port.
hps://test03:5555/calc: RESTCalcService/1.0/postCalc resource is invoked.
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.

M
Odd Header
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 XPath XML schema
text/xml
text/html
multipart/form-data
multipart/mixed
application/json JSONPath JSON schema
application/json/badgerfish
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


M
Even Header
2. Select General > Custom Content-types.

3. Provide the Content-type that has to be configured.
4. Select the Base type as one of the following:
JSON: Specifies that the base-type for the provided Content-type is set to JSON.
XML: Specifies that the base-type for the provided Content-type is set to XML.
Text: Specifies that the base-type for the provided Content-type is set to plain
text.
5. Click .
You can configure multiple custom content-types by clicking Add.
Configuring API Callback Processor Settings

You can configure the API callback processor seing 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 seings 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 seings.
To configure API callback processor settings

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 seing 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.

M
Odd Header
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.
Transaction Alerts
API Gateway supports core as well as transaction-based licensing model. When API
Gateway uses a transaction-based licensing model, then each service invocation is
considered as a transaction and API Gateway keeps a track of these transactions. API
Gateway transactions for the current month is compared with the maximum number of
transactions allowed in a month. The maximum number of transactions that are allowed
in a month The transaction limit is based on the subscription that you have chosen.
When the calculated transaction count is higher than the maximum transactions allowed
per month, users are notified through an email, through a notification that appears in
the API Gateway UI or through a configured webhook. You must have the manage user
administration functional privilege assigned to view the usage details in the Analytics >
API usage details page.
Configuring Criteria for a Transaction Alert Notification Across Stages

You can configure alert notifications through email or web hooks when the total
transactions reaches a particular limit across all stages.
To configure the license alert criteria

2. Select General > Transaction alerts > All stages.
This displays a list of available alert configurations and the corresponding details.
3. Click Add Criteria and provide the following information:

M
Even Header
Field Description
Notify at Select the usage percentage at which the notification is to

be sent.
Notify through The user can be notified through one or both of the
following ways by selecting the appropriate options:
Email: Select this option and provide a valid email
address to which the license alerts are sent. You can add
multiple email addresses by clicking .
Webhook: You have to configure the webhook to invoke a
HTTP call back to send the transaction alert notifications.
Select this option and provide the following information:
URL: Mandatory. Specifies the REST endpoint URL to
invoke the HTTP call back to.
Username: The username information to be sent
through the Authorization header.
Password: The username information to be sent
through the Authorization header.
Header key: The HTTP header key that should be
included in the header of API requests
Header value: The HTTP header value that should be
included in the header of API requests
Note: You can add multiple key-value pairs by

clicking .
4. Click Save.
Schema
When you select the webhook to invoke a HTTP callback to send an alert notification the
following response payload is sent in the webhook notification.
{
"type": "object",
"properties": {
"notificationSetForPercentage": {
"type": "integer",
"title": "The notification percentage",
"description": "The transaction limit percentage at which notifications
should be generated.",
"examples": [
90
]
},

M
Odd Header
"totalTransactions": {
"type": "integer",
"title": "The number of transactions allocated",
"description": "The total number of transactions per month allocated
for a particular customer.",
"examples": [
10000000
]
},
"usedTransactions": {
"type": "integer",
"title": "The number of transactions consumed ",
"description": "The total number of transactions consumed presently
by the consumers.",
"examples": [
1000000
]
},
"percentageUsed": {
"type": "integer",
"title": "The percentage of transaction usage ",
"description": "The rate of transaction usage computed as
usedTransactions/totalTransactions.",
"examples": [
10
]
},
"notificationSentDate": {
"type": "integer",
"title": "The date of notification",
"description": "The date (in long value) at which the notification was
generated for the transaction limit consumption.",
"examples": [
1524646797
]
}
},
"required": [
"notificationSetForPercentage",
"totalTransactions",
"usedTransactions",
"percentageUsed",
"notificationSentDate"
]
}
An example of a sample payload schema would look like:

{
"notificationSetForPercentage": 90,
"totalTransactions": 10000000,
"usedTransactions": 1000000,
"percentageUsed": 10,
"notificationSentDate": 1524646797
}
Modifying Transaction Alert Configurations

To modify a transaction alert criteria

M
Even Header
2. Select General > Transaction alerts.

3. In the Transaction alert configurations list, locate the alert that you want to modify
and click in the Action column.
4. Incorporate the required changes.
5. Click OK.
Deleting a Transaction Alert Configuration

To delete a transaction alert criteria
2. Select General > Trasaction alerts.
3. In the Transaction alert configurations list, locate the row that contains the alert
criteria you want to delete, and click .
The alert criteria is deleted from the Trasaction alert configurations list.
Security Configuration
You must have the API Gateway's manage security configurations functional privilege
assigned to perform the following tasks in the security configuration section of API
Gateway:
Configure the keystores and truststores required for incoming message-level
security.
Configure the SAML issuer to use in API Gateway outbound authentication to fetch
the SAML token from the STS (Security Token Service).
Configure the custom assertions to use in inbound authentication of API Gateway.
Configure Kerberos seings.
Configure JSON web token(JWT), OAuth, and OpenID authorization servers and
third-party providers.
Keystore and Truststore

Keystores and truststores are secure files with industry-standard file formats. The
keystore file stores the private keys and SSL certificates and the truststore file stores the
trusted roots for the certificates.
A keystore file contains one or more pairs of a private key and signed certificate
for its corresponding public key. The keystore should be strongly protected with a
password, and stored (either on the file system or elsewhere) so that it is accessible only
to administrators.

M
Odd Header
The truststore file functions as a database containing all the public keys for CAs within a
specified trusted directory.
To enable the two-way SSL for an API Gateway service, you must add a valid,
authorized X.509 certificate along with the private key in a keystore file, and the
certificate of the client or partner in the truststore file. These keystore and truststore files
have to referred to in the HTTPs port that is used to access the API Gateway service.
API Gateway has a sample keystore that contains self-signed certificates. Software AG
recommends not to use them for configuring SSL communication with API Gateway in a
production environment.
Note: Any modifications to the keystore and truststore aliases in Integration Server
do not reflect in API Gateway. Hence, Software AG recommends that you
do not modify the aliases through the Integration Server Administrator. On
migration from 10.0 to 10.1, the existing configuration in 10.0 is migrated to
the API Gateway UI.
Configuring Keystore Information

To configure Keystore information
2. Select General > Security.
A list of existing keystores and truststores and corresponding details are displayed.
3. In the Keystores section, click Add keystore.
4. In the Create keystore section, provide the following information:
Field Description
Alias A text identifier for the keystore file.

The alias name can contain only leers, numbers
and underscores. It can not include a space,
hyphen and special characters.
The keystore contains the private keys and
certificates (including the associated public keys)
for an Integration Server, partner application, or
Integration Server component.
Select file Select a keystore file of the specified type using

Browse. Select the required file and upload it.
Password Password for the saved keystore file associated

with this alias.

M
Even Header
Field Description
Type The certificate file format of the keystore file, which

by default is JKS for keystores. You can also use
PKCS12 format for a keystore.
Description Optional. A text description for the keystore alias.
5. Click OK.
All the key aliases in the uploaded file are listed.
6. Type a password for the required key alias.
7. Click Save.
The keystore is configured and the alias listed in the keystore alias table.
Note: If a wrong password has been provided for the keystore or one of its
aliases, API Gateway saves the keystore but it is not loaded. The keystore
alias is displayed as the loaded icon with an X mark in the keystore listing.
Configuring Truststore Information

To configure truststore information
A list of existing keystores and truststores and corresponding details are displayed.
3. In the Truststores section, click Add truststore.
4. In the Create truststore section, provide the following information:
Field Description
Name A name for the truststore file.

The alias name can contain only leers, numbers
and underscores. It can not include a space,
hyphen and special characters.
The truststore contains the trusted CA certificates
for an Integration Server, partner application, or
Integration Server component.
Upload truststore file Select a truststore file of the specified type using
Browse. Select the required file and upload it.

M
Odd Header
Field Description
Note: Supports only JKS file format.
Password Password that is used to protect the contents of the

truststore.
This password must have been defined at
truststore creation time using a keystore utility.
Make sure you have the truststore password
available when managing its corresponding
truststore alias.
Description Optional. A text description for the truststore alias.
5. Click Save.
The truststore is configured and the alias listed in the truststore alias table.
Note: If a wrong password has been entered for the truststore, API Gateway
saves the truststore but it is not loaded. The truststore alias is displayed as
the loaded icon with an X mark in the truststore listing.
Configuring Keystore and Truststore Information

API Gateway includes a list of SSL keystores and truststores.
You might want to configure API Gateway to refer to a default keystore, truststore, or
both, before deploying any SOAP message flows that require signature, encryption,
X.509 authentication, and so on, as configured in the Inbound Authentication - Message
policy. The default keystore and truststore are that you want API Gateway to use for the
incoming secured messages.
To configure Keystore and truststore information

A list of existing keystores and truststores loaded during 10.1 first startup and those
created in API Gateway and corresponding details are displayed.
3. Provide the following information in the Configure keystore and truststore seings
section:
Field Description
Keystore alias Select a keystore that API Gateway uses for

incoming message-level security.

M
Even Header
Field Description
Lists all available keystores. If you have not

configured an Integration Server keystore the list is
empty.
Key alias (signing) Select the alias for the private key to sign the
outgoing response from API Gateway to the
original client.
This alias value validates the inbound requests
to API Gateway and signs the outgoing response
from API Gateway to the original client. It is auto-
populated based on the keystore selected. This
field lists all the aliases available in the chosen
keystore. If there are no configured keystores, this
field is empty.
Truststore alias Select a truststore that establishes the HTTPS

connection to the client application.
It contains public certificates that are trusted by
API Gateway.
4. Click Save.
Note: While securing the SOAP APIs using WS-Security policies, you have to
perform the following: restart the server after configuring keystore and
truststore information for the configuration to take effect. This is not required
for REST APIs.
1. Deactivate the APIs that have Inbound Authentication - Message policy
enforced.
2. Update the keystore and truststore configuration.
3. Activate the APIs that were deactivated.
Modifying Keystore Information

To modify keystore information
A list of keystores and truststores and corresponding details are displayed.
3. Click the keystore alias to be updated.
The update keystore section is displayed.

M
Odd Header
4. Modify the fields as required.

5. Click Save.
The set of available aliases is displayed.
Note: If the keystore file is not updated during the edit, then clicking Save closes
the form. If a different keystore file is uploaded, then the list of aliases in
the file is loaded and you are prompted to configure the passwords for the
aliases.
6. Type a password for the alias to be configured.

7. Click Save.
The keystore is updated.
Deleting Keystore Information

Be careful while deleting the keystore information. If the keystore and one of its key
aliases is configured in the keystore seings and the keystore gets deleted, then the
configuration would have issues.
To delete keystore information

3. Click in the action column of the keystore to be deleted.
The keystore is deleted from the list.
Modifying Truststore Information

To modify truststore information
3. Click the truststore alias to be updated.
The update truststore section is displayed.
5. Click Save.
The truststore is updated.

M
Even Header
Deleting Truststore Information

Be careful while deleting the truststore information. If the truststore seings and the
truststore gets deleted, then the configuration would have issues.
To delete keystore information

3. Click in the action column of the truststore to be deleted.
The truststore is deleted from the list.
SAML Issuer
If a native API is enforced with the SAML policy, API Gateway uses this configuration to
communicate to STS (Security Token Service) to retrieve the SAML token.
To add a SAML issuer

2. Select Security > SAML issuer.
The SAML issuer page lists all the issuers configured along with the Endpoint URI
corresponding to each SAML issuer, if any.
3. Click Add SAML issuer.
4. In the Add SAML issuer section, provide the following information:
Field Description
Name Name of a SAML token issuer used by API Gateway.

This value must match the value of the Issuer field in
the SAML assertion.
Normal client Selecting this sets the client that requests the SAML
token.
Act as delegation Selecting this delegates the SAML request to another

user (delegator).
The delegator uses a signature element to authenticate
the SAML request.

M
Odd Header
Field Description
Issuer policy Specifies the name of an issuer policy to be used to

communicate with SAML issuer.
If a value is specified for the Issuer policy field, then
the selected issuer policy is applied to all APIs that
are using the SAML authentication.
If a value is NOT specified for this field, then a
default issuer policy based on the WSS Username or
Kerberos communication mode is applied to all APIs.
Communicate using. Specifies the mode of communication.
WSS Username Specifies that WSS Username mode is used to obtain

the SAML assertion to access the API.
The WSS username token supplied in the header of the
SOAP request that the consumer application submits
to the API.
Kerberos Specifies that Kerberos mode is used to obtain the

SAML token and assertion to access the API.
Transports the Kerberos token over the Transport
Layer Security (TLS) protocol to provide additional
security features.
Authenticate using. Specify the type of authentication you want to use while
communicating with the SAML issuer.
For the Authentication type WSS Username, authenticate using the following:
Custom credentials Specifies the values provided in the policy required to

communicate the SAML issuer.
Provide the following information:
Username. Specify a username.
Password. Specify a password.
Domain. Specify a domain.
For the Authentication type Kerberos, authenticate using any of the following:
Custom credentials Specifies the values provided in the policy required to

communicate the SAML issuer.

M
Even Header
Field Description

Client principal. A valid client LDAP user name.
Client password. A valid password of the client LDAP
user.
Service principal. A valid Service Principal Name
(SPN). The specified value is used by the client to
obtain a service ticket from the KDC server.
Service principal nameform. Specifies the format in
which you want to specify the principal name of the
service that is registered with the principal database.
Select one of the following:
Username. Represents the principal name
as a named user defined in LDAP used for
authentication to the KDC.
Hostbased. Represents the principal name using
the service name and the host name, where host
name is the host computer.
Delegate incoming Specifies the values provided in the policy required

credentials by the API providers to select whether to delegate the
incoming Kerberos token or act as a normal client.
Client password. A valid password of the client LDAP
user.

M
Odd Header
Field Description
Incoming HTTP Specifies the incoming HTTP basic authentication

basic auth credentials in the transport header of the incoming
credentials request for client principal and client password.
Endpoint URI Provide the endpoint URI of the STS.
SAML version Specify the SAML version to be used for

authentication.
Available values are: SAML 1.1, SAML 2.0
WS-Trust version Specify the WS-Trust version that API Gateway must
use to send the RST to the SAML issuer.
Available values are: WS-Trust 1.0, WS-Trust 1.3
Applies to Specify the scope for which this security token is

required.
For example, the APIs to which this token is applied.
Signing configurations
Keystore alias Specify the keystore to be used by API Gateway while

sending the request to the STS.
A keystore is a repository of private keys and
corresponding public certificates.

M
Even Header
Field Description
Key alias (signing) Specify the key alias, a private key used to sign the
request sent to STS.
Encryption configurations
Truststore alias Select the truststore that should be used by API

Gateway while sending the STS request.
Truststore is a repository that holds all the trusted
public certificates.
Certificate alias Select the certificate from the truststore used to encrypt
(Encryption) the request that is sent to the STS.
Request security token template parameters. Defines extensions to the

<wst:RequestSecurityToken> element for requesting specific types of keys,
algorithms, or key and algorithms, as specified by a given policy in the return
token(s).
Key Specifies the key type of the security token template.
Value Specifies a value for the request token.

You can add multiple key and values by clicking
.
5. Click Add.
This adds the SAML issuer and it is listed in the SAML issuers list.
Custom Assertions
API Gateway uses WS-Security (WSS) to provide message-level security and protection
for SOAP message requests from a client to an API, and SOAP message responses from
an API to a client. By default, API Gateway supports the WSS policies like Username,
X.509 certificate, Security Assertion Markup Language (SAML), Kerberos, Encryption,
and so on, for the request or response SOAP messages, or both.
API Gateway also provides an extension to define and use custom policy assertions.
Custom assertions allow the API providers to extend and provide additional security
policies that are not available by default in API Gateway.
In WS-Security, custom assertions are used for expressing individual security
requirements, constraints, or both. The individual policy assertions can be combined

M
Odd Header
to create security policies that ensure secure and reliable exchanges of SOAP messages
between a client and a SOAP API.
API Gateway supports the following assertion types for enforcing a custom security
policy:
Binding Assertions
These assertions specify the security mechanism that is to be used by the client or API
such as the keys being used, algorithms, and so on. Common properties used by other
assertions are also defined in the security binding assertion.
API Gateway supports the following WS-SecurityPolicy binding assertions:
Binding Assertion Description
Transport This assertion is used when the message is protected at the

Binding transport level. In this binding, messages are exchanged
only through a defined medium, for example, HTTPS.
Note: By default, API Gateway uses the transport binding

for Kerberos authentication.
Asymmetric This assertion is used when both the initiator and the
Binding recipient possess security tokens. In this binding, initiator
uses it's private key to sign and the recipient's public key
to encrypt. Recipient uses it's private key to decrypt and
initiator's public key to verify the signature.
Note: By default, API Gateway uses the asymmetric binding

for the security policies.
Symmetric This assertion is used when only the initiator or recipient

Binding has a security token. In this binding, both the signing and
encrypting of messages is done using a single security
token.
Token Assertions
These assertions specify the types of tokens to be used to authenticate and secure SOAP
messages.
API Gateway supports the following WS-SecurityPolicy token assertions:
Token Assertion Description
Username Token When using this assertion, the message-level security is

implemented using a WSS username token. The assertion
authenticates a client using the username and password

M
Even Header
Token Assertion Description

in the SOAP request. If validation of the username token
succeeds, then API Gateway passes the message to the
API. If validation fails, then API Gateway returns a SOAP
fault.
X509 Token When using this assertion, the message-level security is

implemented using an X.509v3 certificate. The assertion
authenticates a client using the X.509v3 certificate in the
SOAP request. If validation of the X.509v3 certificate
fault.
Kerberos Token When using this assertion, the message-level security

is implemented using a Kerberos token. The assertion
authenticates a client using the Kerberos token in the
SOAP request. If validation of the Kerberos token
fault.
SAML Token When using this assertion, the message-level security is

implemented using a SAML (Security Assertions Markup
Language) token. SAML is a standard data format for
exchanging authentication and authorization data between
the client and the SOAP API. If validation of the SAML
token succeeds, then API Gateway passes the message to
the API. If validation fails, then API Gateway returns a
SOAP fault.
Note: API Gateway supports both the SAML 1.1 and 2.0
standards.
Policy Assertions
API Gateway allows you to even define a complete custom policy assertion. For
example, a policy assertion might specify a symmetric binding and the security token
types that are used to digitally sign or encrypt SOAP messages between the client and
API.
Creating a Custom Assertion

Pre-requisites:
assigned to add a custom assertion.

M
Odd Header
You might want to create a custom assertion when you want to:
Enforce symmetric binding with an authentication mechanism that is not available
by default in API Gateway.
Support signing and encryption at the desired level.
Modify the predefined encryption algorithm and security layout properties.
Enforce custom authentication tokens that are not available by default in API
Gateway.
Important: When creating a custom assertion, make sure that both the syntax and the
semantics of the assertion element are valid and in compliance with the Web
Services Security Policy specification.
To create a custom assertion

2. Select Security > Custom assertions.
API Gateway displays a list of all the currently defined policy assertions.
3. Click Add assertion.
4. Select the assertion type. The available options are:
Binding
Token
Policy
5. Provide the following information:
Field Description
Name Name of the custom assertion.

For a binding or token assertion type, this is the display
name of the assertion in the Binding Assertion field or
Custom Token Assertion of the Inbound Authentication -
Message policy.
For a policy assertion type, this is the display name of
the assertion in the Issuer Policy field of the Add SAML
Issuer configuration page.
Select file Click Browse and select the policy assertion file to be
uploaded.
The Assertion element text box displays the data from
the assertion file.

M
Even Header
Field Description
If you have uploaded the policy assertion file and want

to replace it, click the Delete icon.
Assertion element If you have not uploaded the policy assertion file,
provide the XML representation of assertion.
6. Click Add.
The custom assertion is added. You can create as many custom assertions you
require.
Post-requisites:
To enforce the custom binding or token assertion in an API, select the assertion in the
appropriate fields of the Inbound Authentication - Message policy:
Binding Assertion
Custom Token Assertion
To enforce the custom policy assertion in an API, select the assertion and the
corresponding SAML issuer in the appropriate fields:
Issuer Policy field of the Add SAML Issuer configuration page.
Authentication scheme field of the Outbound Authentication - Message policy.
Viewing Custom Assertion List and Assertion Configuration

You can view the list of configured custom assertions in API Gateway. In addition, you
can view and modify the configuration in the individual custom assertion details page.
To view a list of custom assertions and assertion configuration

A list of all available custom assertions appears.
You can delete a custom assertion by clicking its Delete icon.
3. Click any custom assertion to view the configuration details.
The custom assertion details page displays the XML element.
Modifying Custom Assertion

Pre-requisites:
assigned to modify a policy assertion.

M
Odd Header
You might want to modify a custom assertion to change the currently defined security
seings, such as, authentication scheme, signing and encryption, algorithms and
supporting tokens, of SOAP messages.
To modify a custom assertion

3. Select the required custom assertion that you want to modify.
5. Click Save.
The custom assertion is updated.
Post-requisites:
When you are ready to put the policy assertion into effect in an API, select it in the
appropriate field of Inbound Authentication - Message policy.
Deleting Custom Assertion

Pre-requisites:
assigned to delete a policy assertion.
You delete a policy assertion to remove it from API Gateway permanently.
To delete a policy assertion

3. Click in the action column of the custom assertion to be deleted.
The custom assertion is deleted from API Gateway.
Example: Custom Assertions

API Gateway, by default, uses the asymmetric binding assertion with X.509v3 token for
implementing SOAP message protection. If you would like to enforce any authentication
(other than the predefined authentications shipped with API Gateway), include
additional WSS custom assertions, sign and encrypt SOAP messages, and define custom
properties, such as the algorithms and layout of security header, you can create custom

M
Even Header
assertions that would construct the custom policy file to suit your specific security
requirements.
Following is a policy file that API Gateway generates when a WSS username token is
enforced by the Inbound Authentication Message policy for an API.
<wsp:Policy wsu:Id="9dbda2fb-9cef-4ff9-bc70-115c942a3b76"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsp:ExactlyOne>
<wsp:All>
(L01) <sp:AsymmetricBinding xmlns:sp=
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsp:Policy>
<sp:InitiatorToken>
<wsp:Policy>
<sp:X509Token sp:IncludeToken
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702
/IncludeToken/Never">
<wsp:Policy>
<sp:WssX509V3Token10 />
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:InitiatorToken>
<sp:RecipientToken>
<wsp:Policy>
<sp:X509Token sp:IncludeToken=
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy
/200702/IncludeToken/Never">
<wsp:Policy>
<sp:WssX509V3Token10 />
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:RecipientToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:TripleDesRsa15 />
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Strict />
</wsp:Policy>
</sp:Layout>
<sp:ProtectTokens/>
</wsp:Policy>
</sp:AsymmetricBinding>
<sp:SupportingTokens xmlns:sp=
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
<wsp:Policy>
<sp:UsernameToken sp:IncludeToken=
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/
IncludeToken/AlwaysToRecipient"/>
</wsp:Policy>
</sp:SupportingTokens>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>

M
Odd Header
You might have a requirement to change the policy assertion that is available by
default in API Gateway. For example, you might want to generate the above security
policy using a symmetric binding instead of the default asymmetric binding, and
modify the username token that is defined by default as a supporting token to a signed
supporting token. You could then create custom policy assertions to achieve these
specific requirements.
Important: When adding a custom policy assertion, make sure that both the syntax and
the semantics of the assertion are valid and in compliance with the Web
Services Security Policy specification.
Symmetric Binding Assertion

You might want to use a symmetric binding (instead of the default asymmetric binding)
when only API Gateway possess the X.509v3 token for authentication. You might also
want to sign and encrypt the SOAP messages, modify the encryption algorithm, and
include timestamp on the SOAP messages. You would then create a custom binding
assertion with the specific property lines:
<sp:SymmetricBinding
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
<wsp:Policy>
<sp:ProtectionToken>
<wsp:Policy>
IncludeToken/AlwaysToRecipient">
<wsp:Policy>
<sp:WssX509V3Token10/>
<sp:WssX509PkiPathV1Token10/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:ProtectionToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:TripleDesRsa15/>
</wsp:Policy>
<sp:Layout>
<wsp:Policy>
<sp:Strict/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
<sp:ProtectTokens/>
<sp:OnlySignEntireHeadersAndBody/>
<sp:SignBeforeEncrypting/>
</wsp:Policy>
</sp:SymmetricBinding>
You could create custom assertions to include one or more of the following security
requirements:
Supporting Token Assertions

M
Even Header
You might want to sign the supporting token for example, WSS username token, and
use SignedSupportingTokens assertion. You might also want to specify that the signed
username token must always be included in the messages sent to the recipient. You
would then create a custom token assertion with the specific property lines:
<sp:SignedSupportingTokens xmlns:sp=
<wsp:Policy>
</wsp:Policy>
</sp:SignedSupportingTokens>
WSS Token Assertions

You might want to include WSS10 and WSS11 assertions to provide additional SOAP
message security. You would then create two separate custom token assertions with the
specific property lines:
Wss10 assertion:
<sp:Wss10
<wsp:Policy>
<sp:MustSupportRefIssuerSerial/>
</wsp:Policy>
</sp:Wss10>
Wss11 assertion:
<sp:Wss11
<wsp:Policy>
<sp:MustSupportRefThumbprint/>
<sp:RequireSignatureConfirmation/>
</wsp:Policy>
</sp:Wss11>
After you have defined these custom assertions in API Gateway, execution of a policy
that is configured with all of these custom assertions in the Inbound Authentication -
Message policy, would construct the custom security policy file as follows:
<wsp:Policy wsu:Id="1e747a18-b55d-4e99-ac67-80a8eafd76b3"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsp:ExactlyOne>
<wsp:All>
<sp:SymmetricBinding xmlns:sp=
<wsp:Policy>
<sp:ProtectionToken>
<wsp:Policy>
IncludeToken/AlwaysToRecipient">
<wsp:Policy>
<sp:WssX509PkiPathV1Token10/>

M
Odd Header
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:ProtectionToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:TripleDesRsa15/>
</wsp:Policy>
<sp:Layout>
<wsp:Policy>
<sp:Strict/>
</wsp:Policy>
</sp:Layout>
<sp:OnlySignEntireHeadersAndBody/>
</wsp:Policy>
</sp:SymmetricBinding>
<sp:SignedSupportingTokens xmlns:sp=
<wsp:Policy>
</wsp:Policy>
</sp:SignedSupportingTokens>
<sp:Wss11 xmlns:sp=
<wsp:Policy>
<sp:MustSupportRefThumbprint/>
<sp:RequireSignatureConfirmation/>
</wsp:Policy>
</sp:Wss11>
<sp:Wss10 xmlns:sp=
<wsp:Policy>
</wsp:Policy>
</sp:Wss10>
<sp:EncryptedParts xmlns:sp
<sp:Body/>
</sp:EncryptedParts>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
Kerberos Settings
Kerberos is an authentication protocol that uses symmetric encryption and a trusted
third party system to validate the identity of clients. The Kerberos protocol provides
authentication over open and insecure networks in which communication between the
hosts can be intercepted.
You can use API Gateway to configure Kerberos authentication for API requests. API
Gateway provides support for using Kerberos authentication for inbound and outbound
HTTP and HTTPs requests at the transport and the message level.
Kerberos authentication system consists of the a Kerberos client that needs to access
and use Kerberos services, a trusted third-party system, specifically a Key Distribution

M
Even Header
Center (KDC) and a server that hosts APIs that are accessible using Kerberos
authentication.
Note: You can configure the kerberos seings through API Gateway and Integration
Server UI. But, Software AG recommends to use API Gateway UI to configure
or modify instrospection endpoint.
Configuring API Gateway to Use Kerberos

Before you configure API Gateway to use Kerberos authentication, ensure that:
A working Key Distribution Center (KDC) is set up.
The KDC is configured as an LDAP directory, for authenticating incoming requests
with Kerberos tickets.
The Kerberos client is registered with the principal database of the KDC.
The API that you want to access is registered with the KDC.
A valid Kerberos configuration file is available.
To configure API Gateway to use Kerberos

2. Select Security > Kerberos.
3. Click Edit.
4. Provide or modify the following information as required:
Field Description
Realm Optional. The domain name of the Kerberos server, in

uppercase leers.
Note: A value specified for Realm overwrites the realm set

in the KDC configuration file specified in Kerberos
configuration file.
Key Optional. The host name of the machine on which the KDC
distribution resides.
center
A value specified for Key distribution center overwrites the
default key distribution center set in the KDC configuration
file specified in Configuration file.
Configuration The location of the Kerberos configuration file that contains

file the Kerberos configuration information, including the
locations of KDCs, defaults for the realm and for Kerberos

M
Odd Header
Field Description
applications, and the host names and Kerberos realms
mappings.
Use subject Specifies whether API Gateway requires a Kerberos V5

credentials Generic Security Services (GSS) mechanism to obtain the
necessary credentials from an existing subject set up by
the JAAS authentication module. Here, subject represents
the user or service being authenticated in the JAAS login
context.
5. Click OK.
OAuth, JWT, and OpenID Configuration

This section describes the Open Authorization (OAuth), JSON Web Token (JWT), and
OpenID Connect (OpenID) authentication protocols that you can use to identify and
authorize a client application. The application is first identified based on the criteria
provided in the strategy configured. A strategy is a way to authenticate the incoming
request and provides multiple authentication mechanisms or multiple authorization
servers for a single authentication scheme. API Gateway identifies the application and
validates the token submied through the strategy configured in the application.
OAuth Authentication Use case and Workflow

The Open Authorization is a flexible authorization framework for securing application
access to protected resources of APIs. OAuth 2.0 uses access tokens that are presented by
client applications (on behalf of the end users) to access the protected resources.
The OAuth authorization framework includes the following terms:
Roles
Resource Owner (or the End User). This is the holder of the protected resources that
the client application accesses. The resource owner is typically a person (usually the
end user), but could also be an application.
Client Application (or the Client). This is the application that is requesting access to
protected resources on behalf of the end user.
Resource Server (or API Gateway). This is the server that stores the protected
resources the application is trying to access. API Gateway acts as a resource server.
Authorization Server. This is the server that acts as an interface between the client
application and end user, authenticates the end user, and issues access tokens
after proper authorization. API Gateway can be configured to act as an OAuth 2.0
authorization server. You can configure API Gateway for use with a third-party
OAuth 2.0 authorization server, such as PingFederate.

M
Even Header
Clients
Confidential. A confidential client is an application that is capable of keeping a client
password confidential to the world. This client password is assigned to the client
app by the authorization server. This password is used to identify the client to the
authorization server, to avoid fraud. An example of a confidential client could be a
web app, where no one but the administrator can get access to the server, and see the
client password.
Public. A public client is an application that is not capable of keeping a client
password confidential. For instance, a mobile phone application or a desktop
application that has the client password embedded inside it. Such an application
could get cracked, and this could reveal the password. The same is true for a
JavaScript application running in the users browser. The user could use a JavaScript
debugger to look into the application, and see the client password.
API Gateway can be used as an authorization server and as a resource server.
API Gateway as a Resource Server

When API Gateway acts as a resource server, it hosts the protected resources, and
accepts and responds to the client applications' requests that include an access token.
The client application sends the access token in the Authorization request header field
using the Bearer authentication scheme. The resource server validates the access token
locally or remotely if it cannot validate locally.
If the token is valid and the client application has privileges to access the protected
resources, the resource server executes the request. If the access token is invalid, it rejects
the request.
API Gateway as an Authorization Server

When API Gateway acts as an authorization server, it receives authorization requests
from client applications. The authorization server handles the interactions between the
client application, resource server, and resource owner for approval of the request.
As an authorization server API Gateway issues tokens to client applications on behalf
of a resource owner for use in authenticating subsequent API calls to the resource
server. The resource server hosts the protected resources, and can accept or respond
to the protected resource requests using access tokens. If the client application is
authorized to access the protected resources, the resource server executes the request.
The authorization server retains the information about the access tokens it issues,
including the user information. When a client presents an access token to the resource
server, the resource server sends the token to the authorization server to ensure that the
token is valid and that the requested service is within the scope for which the access
token was issued. A scope is the definition of the resources that the client application can
access on behalf of a resource owner. If the client application does not have privileges to
access the resources, the resource server rejects the request.

M
Odd Header
Using API Gateway with an External Authorization Server

When API Gateway is the resource server, you must specify an authorization server. As
an alternative to using API Gateway as the authorization server, you can use a third-
party server as the authorization server. This allows API Gateway to validate access
tokens issued by third-party servers and also allow to dynamically create clients in the
third-party server.
Note: Before you configure API Gateway to use a third-party authorization

server, make sure that the authorization server is compliant with the RFC
7662, OAuth 2.0 token introspection.
From API Gateway release 10.3 onwards API Gateway supports multiple
authorization servers.
To use an external authorization server, you must configure your third-party

authorization server. This includes, but is not limited to, the following:
To introspect the token, you should have a JWKS URI or you should create a client
account that API Gateway uses to call the authorization server's introspection
endpoint.
Make a note of the client_id and client_secret values. You provide this information as
part of defining the external authorization server alias for the API Gateway resource
server.
Make a note of the URL for the introspection endpoint. You provide this information
as part of defining the external authorization server alias in the API Gateway
resource server.
Create the required scopes.
Configure an alias to the authorization server.
Currently, API Gateway, by default, can be used with the following third-party
authorization servers, but are not limited to, that are RFC 7662, OAuth 2.0 token
introspection compliant:
Okta
PingFederate
You can also use other third-party authorization servers like Google, keycloak, and so
on.
Use case 1: OAuth Authentication with API Gateway as a Resource server as well as an
Authorization server
This describes the high level workflow for the scenario where API Gateway is a resource
server as well as an Authorization server.
1. Configure API Gateway as an internal authorization server.

M
Even Header
Ensure you configure OAuth scopes while configuring the authorization server.
For a complete procedure on configuring API Gateway as an internal authorization
server, see “Configuring the Internal Authorization Server” on page 92.
2. Map the scopes.
For a complete procedure on mapping scopes, see “Mapping OAuth or OpenID
Scopes” on page 102.
3. Enforce the Identify and authorize application policy on the API.
Ensure to select OAuth2 token. For details of the Identify and authorize application
policy see, “Identify and Authorize Application” on page 253.
4. Associate an application with the API.
You can create a new application or use an existing one. Ensure that the application
associated contains the strategy for OAuth authentication. While creating a strategy
you can associate it with the scopes that are available to be used while using
dynamic client registration. For a complete procedure on creating an application
with a strategy, see “Creating an Application” on page 407.
5. Activate the API.
User on invoking the API uses the OAuth identification method to access the
protected resource.
6. Get access token through the following URLS:
invoke/pub.apigateway.oauth2/authorize
invoke/pub.apigateway.oauth2/getAccessToken
7. Use the access token to invoke the API.
Use case 2: Oauth Authentication with API Gateway as a Resource server and an external
Authorization server
This describes the high level workflow for the scenario where API Gateway is the
resource server with a third-party authorization server. This is generally used in an
environment where there is an existing authorization server, which is used with API
Gateway as a resource server.
1. Configure a Provider if you are using the Dynamic client registration. Else you can
proceed to step 2.
For a complete procedure on configuring a provider, see “Adding a Provider” on
page 94
2. Configure an external authorization server.
Ensure you configure OAuth scopes while configuring the authorization server. For
a complete procedure on configuring an external authorization server, see “Adding
an External Authorization Server” on page 97.
3. Map the scopes.

M
Odd Header

Ensure to select OAuth2 token. For details of the Identify and authorize application
policy see, “Identify and Authorize Application” on page 253.
5. Associate an application with the API
You can create a new application or use an existing one. Ensure that the associated
application contains the strategy for OAuth authentication and contains the client
ID. While creating a strategy you can associate it with the scopes that are available to
be used while using dynamic client registration. If the authorization server supports
dynamic client registration, then you can select the option Generate credentials. If
the application is already created in authorization server, then provide the respective
client id. For a complete procedure on creating an application with a strategy, see
“Creating an Application” on page 407.
6. Activate API.
User on invoking the API uses the OAuth identification method to access the
protected resource.
7. Get the access token from the authorization server.
8. Use the access token to invoke the API.
OAuth Authorization Workflow

The flow of authorization requests and responses between the end user, client
application, authorization server, and resource server is as depicted in the following
figure.

M
Even Header
The OAuth authorization workflow is as follows:

1. The end user logs in, the client application sends the authentication request to the
authorization server to obtain an access token.
2. Authorization server validates the request and generates an access token for the
client.
3. Client uses this access token to send HTTP requests to API Gateway.
4. API Gateway then performs the following:
a. Identifies the application using the clientId.
b. Validates the token locally or remotely if it is not possible locally.
c. Checks if the requested resource is part of the scopes in the token.
d. Checks the audience.
If all the above are validated, API Gateway provides access to the protected resource.
If the access token is expired, authorization server returns a specific error response.
The client application can then use Refresh Token to request a new access token.
The Authorization Server returns a new access token that can be used to access the
protected resource.

M
Odd Header
JWT Authentication Use case and Workflow

JSON Web Token is a JSON-based open standard (“RFC 7519”) means of representing a
set of information to be securely transmied between two parties. A set of information
is the set of claims (claim set) represented by the JWT. A claim set consists of zero or
more claims represented by the name-value pairs, where the names are strings and the
values are arbitrary JSON values. The claims in a JWT are encoded as a JSON object that
is used as the payload of a JSON Web Signature (JWS) structure, enabling the claims to
be digitally signed. JWTs can be signed using a shared secret (with HMAC algorithm), or
a public or private key pair using RSA.
API Gateway can generate a JWT token itself or validate the JWT token generated by a
trusted third-party server. API Gateway uses the RSA-based JWT to provide stronger
integrity protection to JWTs when API Gateway is the issuer of the token. The JSON-
based access tokens contain one or more claims. A claim is any piece of information that
serves as an unique identifier, and that the token issuer who generated the token has
verified. API Gateway extracts the claims from the JWT, identifies the application and
then authorizes access to the protected resource.
Note: JWT authentication is supported for both REST and SOAP APIs.
Use case 1: JWT authentication with API Gateway as a JWT issuer

This describes the high level workflow for the scenario where API Gateway can generate
the JSON Web Token itself.
1. Configure API Gateway as an internal authorization server.
For a complete procedure on configuring API Gateway as an internal authorization
server, see “Configuring the Internal Authorization Server” on page 92.
Ensure to select JWT. For details of the Identify and authorize application policy see,
“Identify and Authorize Application” on page 253.
You can create a new application or use an existing one. Ensure that you add the
required claims while creating the application, which you would use to validate the
access token. For a complete procedure on creating an application with a strategy,
see “Creating an Application” on page 407.
User on invoking the API uses the JWT identification method to access the protected
resource.
5. You get the JWT in one of the following ways (with or without claims), which you
can pass as a bearer token to invoke the API.
The following internal APIs are used for user and application authentication.

M
Even Header
getJsonWebtoken
Used for user authentication without custom claims
User authentication happens using the basic auth credentials of any valid IS user.
Method : GET
URL: http://host:port /rest/pub/apigateway/jwt/getJsonWebToken
This endpoint can be used to create a JWT without custom claims
Used for application authentication with custom claims.
If you want to add the custom claims in the JWT then you can use this URL with the
payload specifying the custom claims.
The application is authenticated using the application identifiers supplied in the
request, such as, APIKey or Username or Host name, and then a token is generated
with application id as a subject.
Method: POST
URL: http://host:port /gateway/security/getJsonWebToken
This endpoint can be used to create a JWT with custom claims
Payload
{
"claimsSet": {
"customclaim1": "name ",
"customclaim2":"company name "
}
}
Use case 2: API Gateway with an external JWT issuer

This describes the high level workflow for the scenario where API Gateway accepts
JSON Web Token generated by a trusted third-party server.
For a complete procedure on configuring an external authorization server, see
“Adding an External Authorization Server” on page 97.
Ensure to select JWT. For details of the Identify and authorize application policy see,
“Identify and Authorize Application” on page 253.
You can create a new application or use an existing one. Ensure that you add the
required claims while creating the application, which you would use to validate the
access token and the external authorization server that would be the JWT issuer. For
a complete procedure on creating an application with a strategy, see “Creating an
Application” on page 407.

M
Odd Header

User on invoking the API uses the JWT identification method to access the protected
resource.
5. Pass the JWT as a bearer token to invoke the API.
JWT Authorization Workflow

application, JWT issuer, and resource server is as depicted in the following figure.
The JWT authorization workflow is as follows:

1. The end user logs in, the client application sends an authentication request to API
Gateway or to any third-party JWT issuer, to obtain a JWT token.
2. If API Gateway is the JWT issuer, then it validates the user or the application. If the
user or application credentials are valid, API Gateway generates the JSON token
using a private key that was specified in the JWT configuration, and sends the
generated token to the client.
If the user credentials are invalid, API Gateway returns a specific error response.
3. Client sends the generated JSON token in the HTTP Authorization request header as
a Bearer token to access the protected API in API Gateway.
4. API Gateway first identifies the application based on claims from the JWT, then
validates the JWT using the public certificate of the issuer (the issuer can be API
Gateway or a third-party issuer) and provides access to the protected resources.
If the validation fails, API Gateway returns a specific error response.

M
Even Header
Note: If API Gateway has generated the JSON token, it validates the signature
using a public certificate that was specified in the JWT configuration. Else,
if the HTTP request is sent from a third-party JWT issuer, API Gateway
validates the token using a public certificate or the JWKS URI of the issuer.
OpenID Authentication Use case and Workflow

OpenID Connect is an open standard and decentralized authentication protocol that
extends on the OAuth 2.0 authorization framework. It combines the capability of Open
ID in verifying the client's identity and OAuth's capability of accessing the client's
resources.
In case of OpenID support in API Gateway, you can use the OpenID authentication
protocol to identify and authorize a client application to access the protected resources
in one of the following ways (these are explained in detail in the Usecase section.):
Use just the access tokens (that is OAuth token) to invoke the protected resources.
Use the ID token (that gives information about the user) to invoke the protected
resources in one of the following ways:
Present the ID token to exchange it for an access token and use the access token
to access the protected resources.
Use the ID token directly to access the protected resources.
API Gateway does not act as a OpenID Connect server but can validate the tokens issued
by other OpenID Connect servers.
The following internal API is used for geing an access token for an ID token.
exchangeIDToken
Method: POST
URL: http://host:port /gateway/security/exchangeIDToken
Payload
{
"gatewayScopes": ["OktaTenant1:inventory"],
"idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY"
"expiry": 3000
}
For details on scopes, see “Mapping OAuth or OpenID Scopes” on page 102
Note: The getOpenIDtoken call is deprecated and is no more available from the API
Gateway release 10.3 onwards.
Use case 1: OpenID authentication using OpenID Connect Provider

This describes the high level workflow for using the OpenID authentication protocol to
identify and authorize a client application to access the protected resources.

M
Odd Header
1. Configure a Provider if you are using the Dynamic client registration. Else you can
proceed to step 2.
For a complete procedure on configuring a provider, see “Adding a Provider” on
page 94
Ensure you configure the external authorization server with the introspection
URL and OAuth scopes. For a complete procedure on configuring an external
authorization server, see “Adding an External Authorization Server” on page 97.
3. Map the scopes.
Ensure to select OpenID Connect or JWT as options. For details of the Identify
and authorize application policy see, “Identify and Authorize Application” on
page 253.
You can create a new application or use an existing one. Ensure that the application
associated contains the strategy for OpenID authentication. While creating a strategy
you can associate it with the scopes that are available to be used while using
dynamic client registration. For a complete procedure on creating an application
with a strategy, see “Creating an Application” on page 407.
User on invoking the API uses the access token or the ID token provided by the
provider to access the protected resource.
7. User can access the protected resources in one of the following ways:
The user presents the access token to API Gateway and on validation accesses the
protected resource.
The user presents the ID token to API Gateway to exchange it for an access token
(if the user has configured the OpenID Connect option in step 4). The client
then presents the access token to API Gateway and on validation accesses the
protected resource.
exchangeIDToken
Method: POST
Payload
{

M
Even Header
"expiry": 3000
}
The user presents the ID token as a JWT directly to API Gateway (if the user has
configured the JWT option in step 4), and on validation accesses the protected
resource.
OpenID Authorization Worklow

The OpenID Connect support in API Gateway provides two different ways for a client to
access a protected resource depending on whether the provider has provided an access
token or an ID token. The workflow diagram depicts both these cases. The first 2 steps
are same in both the cases, the arrows in blue depict the flow where an access token is
used to access the protected resource, and the arrows in orange depict the flow where an
ID token is used to access the protected resource.
OpenID authorization workflow using the OpenID Connect Provider
application, OpenID Connect provider, and resource server is as depicted in the
following figure. The client application makes an OpenID call to the OpenID Connect
provider and receives an access token or an ID token in the response. It uses these tokens
to access the protected resources.
OpenID authorization workflow using the access token provided by the Open ID Connect Provider
1. The client makes an OpenID call to the OpenID connect Provider.
2. The OpenID Connect Provider provides an access token to the client.
3. The client application presents the access token received from the OpenID Connect
Provider to send HTTP requests to API Gateway.

M
Odd Header

API Gateway provides access to the protected resource if all the validations are done.
If the access token is valid, API Gateway provides access to the protected resource.
protected resource.
OpenID authorization workflow using the ID token provided by the Open ID Connect Provider
1. The client makes an OpenID call to the OpenID Connect Provider.
2. The OpenID Connect Provider provides an ID token to the client.
3. The client application presents the ID token received from the OpenID Connect
Provider to API Gateway.
4. API Gateway validates the ID token and returns an access token to the client
application.
exchangeIDToken
Method: POST
Payload
{
"expiry": 3000
}
For details on mapping scopes, see “Mapping OAuth or OpenID Scopes” on

page 102
5. The client then uses this access token to send HTTP requests to API Gateway.

M
Even Header
API Gateway provides access to the protected resource if all the validations are done.
If the access token is valid, API Gateway provides access to the protected resource.
protected resource.
Note: The user can present the ID token directly as a JWT to access the protected
resources in case the ID token is provided on configuring the JWT property in
the Identify and authorize application policy enforced on the API.
Configuring the Internal Authorization Server

Pre-requisites:
assigned to add an authorization server.
You have to configure API Gateway with the required information to act as an internal
authorization server for OAuth or JWT depending on what authentication protocol
you want to use to identify and authorize a client application. You can also define the
required scopes that provide a way to limit the amount of access that is granted to an
access token.
To configure an internal authorization server

2. Select Security > OAuth/JWT/OpenID.
3. In the Internal Authorization servers section, click local.
This is the internal authorization server available that you can configure with
required information to act as an internal authorization server for OAuth, JWT or
OpenID authentication protocols.
4. The name field is pre-populated with the name of the internal authorization server,
local, which is non-editable.
5. The description for the internal authorization server is pre-populated with the
description available. You can modify the description as required.
6. Click JWT configuration to configure API Gateway as a JWT issuer.
Alternatively you can expand or collapse a section, using the down arrow ( ) and
the up arrow ( ) and that appear next to the section name.
7. Provide the following information as required:

M
Odd Header
Field Description
Token issuer Name of the JWT token issuer used by API Gateway.
Note: The Token issuer value is case-sensitive.
Algorithm The cryptographic algorithm to sign JSON Web Tokens

(JWTs).
Supported values are: RS256, RS384, and RS512.
Expiry The duration (in minutes) for which the token is valid.
duration
For example, the value 60 denotes that the access token will
expire in one hour from the time the token was generated.
Audience Optional. The intended recipient of the token. The

application that receives the token must verify that the
audience value is correct and reject any tokens intended for
a different audience.
Keystore alias Alias of the keystore containing the private key that is used
to sign JWTs.
The Keystore alias field contains a list of the available
keystore aliases in API Gateway. If there are no
configured keystore aliases, this field displays the
DEFAULT_IS_KEYSTORE.
Key alias Alias of the private key used to sign JWTs.

The Key alias field contains a list of the available aliases in
the selected keystore. If there are no configured keystores,
this field is empty.
8. Click OAuth configuration to configure API Gateway as an OAuth authorization server.
Alternatively you can expand or collapse a section, using the down arrow ( ) and
the up arrow ( ) and that appear next to the section name.
9. Provide the following information as required:
Authorization code expiration interval. Specifies the time (in seconds) during which
the authorization code issued by the authorization server is valid. Valid values
are between 1 and 2147483647. The default value is 600.

M
Even Header
Access token expiration interval. Specifies the time (in seconds) for which the access
tokens issued by the authorization server are valid. The default value is 3600.
Value of -1 specifies that the access token does not expire.
10. Click OAuth tokens.
This lists the available OAuth tokens with the following details:
Client ID. Specifies the ID of the client application that requested the access token.
Owner ID. Specifies the ID of the owner who issues the access token.
Access token. Specifies the access token
Refresh token. You can use to generate a new access token if the existing access
token is expired.
Remaining refresh limit. Displays the remaining aempts for refreshing the access
token.
Action. Revokes the access tokens, which means those tokens cannot be used to
invoke the protected resource.
11. Click OAuth scopes.
OAuth 2.0 scopes provide a way to limit the amount of access that is granted to
an access token. For example, an access token issued to a client application may
be granted READ and WRITE access to the protected resources, or just the READ
access. You can implement your APIs to enforce any scope or a combination of
scopes as required. So, if a client receives a token that has READ scope, and it tries to
invoke an API endpoint that requires WRITE access, the invocation fails.
You can provide the meaning to the scope in OAuth/OpenID scopes management
section.
12. Type the scope that is registered in the authorization server and click +Add.
You can include multiple scopes.
13. Click Update.
This updates the internal authorization server details with the required information
and is listed in the table of Internal authorization server.
Adding a Provider
Pre-requisites:
assigned to add a provider.
The OAuth 2.0 configuration in API Gateway is split into two sections - Providers and
Authorization servers.
You have to add a provider and configure the authorization provider metadata
information in this section for API Gateway to communicate with this provider during

M
Odd Header
dynamic client registration only. If there is any deviation from the actual OAuth
specification then the provider has to be configured for these deviations.
To add a provider
2. Select Security > JWT/OAuth/OpenID.
3. Click Add provider and provide the following information:
Field Description
Name Name of a third-party provider. For example, Amazon.

You can also use one of the following pre-configured
third-party providers that is shipped with the API
Gateway installation:
PingFederate
OKTA
Client metadata field mapping. Specifies the mapping of dynamic client

registration specification to that of the client implementation of the provider.
The Client metadata field mapping fields are required when you are adding a
third-party provider that is not shipped with API Gateway.
Specification The client metadata aributes in accordance with the

name dynamic client registration specification as defined in
RFC 7591.
The available values are:
redirect_uris. Redirection URL that the authorization
server uses to redirect the authorization code once the
authorization request is approved by end user.
Note: If you do not specify this aribute, API

Gateway automatically generates the URL.
token_endpoint_auth_method. The client authentication

method at the token endpoint.
grant_types. The grant type of authorization flow to
obtain authorization codes, ID tokens, and refresh
tokens.
application_type
response_types. The type of response that the client
application uses at the authorization endpoint.

M
Even Header
Field Description
client_name. Name of the client to use to represent

the client application to the end user during
authorization.
client_uri. URL of the client application.
logo_uri. URL of an image to use to represent the client
application to the end user during authorization.
Note: The logo_uri is currently not supported in API

Gateway.
scope. List of user-authorized scopes that the client

uses for requesting access tokens.
Note: If you do not specify this aribute, the

authorization server registers the client with a
default set of scopes.
contacts. The means (for example, Email address) by

which end users can contact the client for support
requests.
tos_uri. URL of the service document for the client that
describes a contractual relationship between the end-
user and the client that the end-user accepts when
authorizing the client.
Note: The tos_uri is currently not supported in API

Gateway.
jwks_uri. URL of the JSON Web Key (JWK) Set

document containing the client's public keys.
Note: The jwks_uri is currently not supported in API

Gateway.
client_id. Identifier that is unique to the client

application.
client_secret. The password or phrase for the client
application to use to authorize communication with
the end user.
Implementation The client metadata aributes that are used by the

name authorization server, but are not in accordance with the
dynamic client registration specification.

M
Odd Header
Field Description
Example:
For the redirect_uris field, provide the value
redirectUris .
For the grant_types field, provide the value grantTypes .
For the client_name field, provide the value name .
For the logo_uri field, provide the value logoUrl .
For the client_id field, provide the value clientId .
For the client_secret field, provide the value secret .
Extended request parameters. Specifies the additional client metadata aributes

that are specific to the authorization server, and are not specified in the
dynamic client registration specification.
In PingFederate (For example):
forceSecretChange = true
Type Specifies the client metadata aribute type.

The available values are: Client read, Client registration,
Client update, Client delete.
Key The client metadata aribute key that is specific to the

authorization server.
Value A value for the client metadata aribute key. When

sending requests to the authorization server, this value
is appended to all requests.
You can add multiple request parameters by clicking + Add.

4. Click Save.
The provider is added and displayed in the list of providers.
Adding an External Authorization Server

Pre-requisites:
assigned to add an authorization server.
As an alternative to using API Gateway as the authorization server, you can use a third-
party server as the authorization server. To use an external authorization server, you
must configure your third-party authorization server.

M
Even Header
To add an external authorization server

2. Select Security > OAuth/JWT/OpenID.
The available and configured internal authorization servers and external
authorization servers are listed in the respective sections.
3. Click Add authorization server in the External authorization servers section.
4. Type a name for the external authorization server.
5. Type a description for the external authorization server that is being configured.
6. Provide the discovery endpoint in the Discovery URL field and click Discover.
When you specify the discovery URL, API Gateway fetches data from the URL
response and auto-populates the fields with the fetched data.
7. Click Introspection and provide the following information to validate the incoming
tokens.
Field Description
Local introspection. Provide the following information to validate the tokens

locally.
Issuer Name of the token issuer.
JWKS URI Specifies JSON Web Key Signature endpoint to fetch the
corresponding public certificates.
Truststore alias Specify the alias of the truststore on API Gateway that
holds the Certificate Authority (CA) certificate of third-
party authorization server.
This is required if the JWKS URI is not available for the
authorization server and you want to configure this
certificate directly.
Certificate alias Alias of the certificate used to validate the token.

The Certificate alias field contains a list of the available
aliases in the selected truststore. If there are no
configured truststores, this field is empty.
Remote introspection. Provide the following information to validate the

tokens remotely if local introspection cannot be done.

M
Odd Header
Field Description
Introspection URL of the token introspection endpoint of a third-party

endpoint OAuth 2.0 authorization server. API Gateway uses the
introspection endpoint to check that access tokens used
in client requests are currently active and are valid to
invoke the protected resources.
Gateway user The name of the Gateway user that API Gateway uses to
invoke the token introspection endpoint.
Client ID ID of the introspection client on the authorization server

that API Gateway uses to introspect the access tokens.
Client secret Password of the introspection client that API Gateway

uses to introspect the access tokens.
8. In the Dynamic client registration section, provide the following information if you
want to dynamically create a client from API Gateway when required.
You would use this configuration only if you do not intend to use any of the existing
clients.
Field Description
Enabled Specifies whether dynamic client registration is enabled.
Click the toggle buon to change the state to to enable

dynamic client registration.
By default this option is disabled.
Provider Select the name of the third-party provider.

name
Client Specifies the corresponding REST endpoint URLs for the

registration client configuration of REST APIs.
URL
Authentication Specifies the type of authentication scheme that API

type Gateway would use to communicate with the external
authorization server for client management.
Select one of the following authentication type:

M
Even Header
Field Description
Basic. Specifies the username and password information

that would be passed in the authorization header of HTTP
request for client authentication.
Username. The username to access the protected
resources of REST APIs.
Password. A valid password associated with the
username.
Token. Specifies the token information that would be
added as a bearer token in the HTTP request for client
authentication.
Token type. The type of token that would be contained in
the HTTP request.
Token. The token that would be contained in the HTTP
requests.
9. In the SSL Configuration section, provide the following information for SSL
configuration, if the authorization server wants the 2-way SSL for the requests.
Field Description
Keystore Alias of the keystore containing the private key that is used
alias for a secured communication between API Gateway and the
You can view all the keystore aliases available in
API Gateway. If there are no configured keystore
aliases, the list box contains only the default keystore,
DEFAULT_IS_KEYSTORE .
Key alias Alias for the private key to use to validate the HTTP requests
from the client.
You can view all the aliases available in the selected keystore.
If there are no configured keystores, this list box is empty.
Truststore Alias of the truststore on API Gateway that holds the

alias Certificate Authority (CA) certificate of third-party
Note: You need to select a truststore alias only when all of the
following are true:
M
Odd Header
Field Description
The client account on the third-party authorization

server is configured to use mutual (two-way) SSL,
and
The authorization server’s Certificate Authority
certificate is not in the set of well-known authorities
trusted by the JVM in which API Gateway runs.
10. In the Metadata section, provide the following information for the authorization
server metadata, which is used for the communication to portal.
Field Description
Access The endpoint URL on the authorization server through

token URL which the client application exchanges the authorization
code, client ID, and client secret, for an access token.
Authorize The endpoint URL on the authorization server through

URL which the end user authenticates and grants authorization to
the client application.
Refresh The endpoint URL on the authorization server through

token URL which the client application refreshes an expired access
token.
11. Click Scopes.

OAuth 2.0 scopes provide a way to limit the amount of access that is granted to
an access token. For example, an access token issued to a client application may
be granted READ and WRITE access to the protected resources, or just the READ
access. You can implement your APIs to enforce any scope or a combination of
scopes as required. So, if a client receives a token that has READ scope, and it tries to
invoke an API endpoint that requires WRITE access, the invocation fails.
You can provide the meaning to the scope in OAuth/OpenID scopes management
section.
12. Provide the scope, in the Scope field that is registered in the authorization server and
click +Add.
You can add more than one scope by clicking +Add.
13. Click Save.
The external authorization server is added. You can add as many authorization
servers as required, but only one is the default at any given time.
M
Even Header
Mapping OAuth or OpenID Scopes

assigned to manage scopes.
You have to map the scope that you have defined in the authorization server with the
APIs in API Gateway to authorize the access tokens to be used to access the protected
resources. You can map either a complete API or parts (resources or methods) of an API
to the scope.
For example, if there is a scope you have defined for an external authorization server,
such as readonly, then the access tokens which contain readonly as their scope, should
access only the GET resources. So, you can create an API Scope for the GET resources in
an API or for multiple APIs and then map this readonly scope to all those API Scopes.
Now this access token can invoke only the GET resources. If it tries to invoke any POST
or PUT resource it fails. As another example you can consider mapping a business scope
such as, inventory, that you have defined in the authorization server; you can map all
the resources required for the inventory business to this scope.
To map a scope
1. Expand the menu options icon , in the title bar, and select OAuth/OpenID scopes.
2. Click Map scope.
3. Provide the following information in the Authorization server scope section:
Field Description
Select authorization server Specifies the scope linked to the authorization

scope server.
Type a search word and select the required
scope from the search list populated.
Name Displays the name of the authorization server

scope selected. This is populated by default and
is non-editable.
Description A brief description for the scope being mapped.
Audience Provide a value or URI, the intended recipient

of the authorization server scope.
The application that receives the token verifies
that the audience value is correct and rejects any
tokens intended for a different audience.
4. Click API scopes.
M
Odd Header
5. Specify an API scope that is to be linked to the authorization server.

Alternatively, you can type a search word and select the required API scope from the
search list populated.
The API scopes added are listed in the Selected API scopes table. You can click the
delete icon , in the corresponding column, to delete an API scope from the list.
6. Click Save.
This maps the authorization server scope to the selected API scopes and lists the
authorization scope in the scopes list.
Viewing Scope Mapping Details

assigned to manage scopes.
You can view the scope details and modify the scope details as required from the
OAuth/OpenID scopes page.
To view scope mapping details

1. Expand the menu options icon , in the title bar, and select OAuth/OpenID scopes.
A list of available scopes appears. The details, such as, name and description of the
scope is displayed in the form of a table. You can delete a scope by clicking the delete
icon .
2. Click a scope.
The scope details page appears. This page displays the details such as the
authorization server name, the server scope, the API scopes that are linked to
the server scope and the API scope details such as the API to which the scope is
associated, the description of the API and API version number.
You can modify the scope by clicking the Edit buon and modifying the required
values.
Viewing Provider List and Provider Configuration

You can view the list of integrated third-party providers and their configuration details,
modify the provider configuration, and delete a provider in the Providers section.
To view a list of providers and provider configuration

2. Select Security > JWT/OAut/OpenID > Provider.
The Providers section displays a list of all the defined third-party providers in API
Gateway.
You can also perform the following operations in the Authorization servers section..
M
Even Header
You can view the configuration details of the provider by clicking the required
provider. The provider details page displays the client metadata field mapping
and extended request parameter configuration information of the selected
provider.
You can edit the provider configuration by clicking the required authorization
server and modifying the details as required.
You can reset the configuration to system default value by clicking in the
Action column for the respective provider.
You can delete the required authorization server by clicking in the Action
column for the respective provider.
Modifying the Provider Configuration

Pre-requisites:
assigned to modify a provider.
You might want to modify a provider to change the currently defined configuration
seings.
To modify a provider configuration

The Providers section displays a list of all the available providers in API Gateway.
3. Click the name of the partner provider you want to modify.
5. Click Save.
The provider is updated.
Viewing Authorization Server List and Server Configuration

You can view the list of authorization servers and their configurations details, modify
the server configuration, and delete an authorization server in the Authorization servers
section.
To view a list of authorization servers and server configuration

The Authorization servers section displays a list of all the internal and external
authorization servers in API Gateway under respective sections.
M
Odd Header
You can also perform the following operations in the Authorization servers section..
You can view the configuration details of the authorization server by clicking
the required authorization server. The authorization server details page displays
the client information, scope information, and token information of the selected
You can edit the server configuration by clicking the required authorization
server and modifying the details as required.
You can delete the required authorization server by clicking in the Action
column for the respective authorization server.
Modifying Authorization Server Configuration

Pre-requisites:
assigned to modify an authorization server.
You might want to modify an OAuth 2.0 authorization server to change the currently
defined configuration seings.
To modify the authorization server configuration

The Authorization servers section displays a list of all the internal and external
authorization servers in API Gateway.
3. Click the name of the authorization server you want to modify.
5. Click Save.
The authorization server is updated.
Deleting an Authorization Server

Pre-requisites:
assigned to delete an authorization server.
You delete an authorization server to remove it from API Gateway permanently.
To delete an authorization server

M
Even Header
The Authorization servers section displays a list of available internal and external
authorization servers in API Gateway.
3. Click in the action column of the authorization server to be deleted.
The authorization server is deleted from API Gateway.
Deleting a Provider
Pre-requisites:
assigned to delete a provider.
You delete a provider to remove it from API Gateway permanently.
Important: You must not delete a provider if it is being used by an authorization server.
To delete a provider
The Providers section displays a list of available providers in API Gateway.
3. Click in the Action column of the provider to be deleted.
The provider is deleted from API Gateway.
Destination Configuration
API Gateway can publish events and performance metrics data to the configured
destinations. Event type data provides information about activities or conditions that
occur on API Gateway. The performance data provides information on average response
time, total request count, fault count, and so on, for the APIs that it hosts.
You must have the API Gateway's manage destination configurations functional
privilege assigned to configure the following destinations to which the event types and
performance metrics data is published:
API Gateway
API Portal
CentraSite
Elasticsearch
Email
M
Odd Header
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

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:
Access profile management
Alias management
Analytics management
API management
Application management
Approval management
Group management
Package management
Plan management
Policy management
M
Even Header
Promotion 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.
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

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.
M
Odd Header
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.
7. 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

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.
M
Even Header

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

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.
M
Odd Header
Field Description
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 Specifies the authorization protocol that is used by the

protocol 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.
M
Even Header
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

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.
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:
M
Odd Header
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

3. Select Elasticsearch > Configuration to configure Elasticsearch as the destination.
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.
M
Even Header
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

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.
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:
M
Odd Header
Access profile management

Alias management
API management
Approval management
Group management
Package management
Plan management
Policy 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 Destination

You have to configure email as a destination to receive alert notifications. The alerts
are sent to the email ID specified in the Log Invocation, Monitor Service Performance,
Monitor Service Level Agreement, and Throling Traffic Optimization policies. Before
configuring email as a destination, you must perform the following email server
configurations to establish a connection between API Gateway and the email server.
To configure Email destination

3. Select Email > Configuration.
M
Even Header
Field Description
SMTP server The server name or the IP address of the SMTP server
that API Gateway uses to send the messages.
Port The port that API Gateway uses to connect to the

specified SMTP server.
Transport layer The SSL encryption type that API Gateway uses when
security communicating with an email server. Use one of the
following transport layer security options:
None. Default. Use an unsecure mode when API
Gateway is communicating with an email server. When
you specify None, the email server authenticates the
email client using only the username and password.
Explicit. Use explicit security when API Gateway is
communicating with an email server. With this type of
security, API Gateway initially establishes an unsecure
connection with the email server and then upgrades to
the secure mode.
With explicit transport layer security, API Gateway
communicates with the email servers that support SSL
encryption and also with those that do not support
SSL encryption. If the email server does not support
transport layer security, API Gateway disconnects the
connection which was established earlier with the email
server. You can then establish an unsecure connection
by selecting None in the Transport layer security field and
enable the port.
Implicit. Use implicit security when API Gateway
communicates with an email server. With this type of
security, API Gateway always establishes an encrypted
connection with the email server. Only clients that
support SSL are allowed to access API Gateway.
Truststore alias The truststore that API Gateway uses while sending the
request to a native API. Truststore is a repository that
stores all the trusted public certificates.
Default email The character set that API Gateway uses to be recognized
charset by the system. Type the character set in the Default
email charset field. By default, API Gateway uses UTF-8
character set for the messages.
M
Odd Header
Field Description
From email The email address from which you want to send the
alerts.
Test email The email address to which you want to send the test
email. This email address can be the same as the From
email address.
5. Click Test.
This tests the communication channel between API Gateway and the configured
email server.
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.
Post-requisites:
After performing the server configurations, select Email as a Destination in the Policies
properties page for each policy, to receive the email alerts 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

3. Select Email > Templates to configure the event templates.
4. Specify the following for the Log Invocation, Monitor Service Level Agreement,
Monitor Service Performance, and Throling 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.
M
Even Header
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 Service
Level Agreement, Monitor Service Performance, and Throling 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 to abandon the changes and revert to the default
template. You can click to review the changes before adding the changes to the
email content.
5. Click Save.
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 aempts) over a period of time. You can use audit logs to view a detailed
record of various auditable events that occurred on the API Gateway objects, user login
and logout operations, and identify the users who are responsible for the changes. You
can configure which audit events to log for a specific destination based on your auditing
requirements.
You can configure API Gateway to log the auditable events for following destinations:
API Gateway
Elasticsearch
The following auditable events can be configured to write to the API Gateway audit
logs:
M
Odd Header
Access profile management events

Access profile management consists of the following events:
Creation, modification, and deletion of an Access profile object.
Alias management events
Alias management consists of the following events:
Creation, modification, and deletion of an Alias object.
Analytics management events
Analytics management consists of the following events:
Archiving, purging, and restoring of analytics data in the database.
API management events
API management consists of the following events:
Creation, modification, and deletion of an API object.
Activation and deactivation of an API.
Application management events
Application management consists of the following events:
Creation, modification, and deletion of an Application object.
Approval management events
Approval management consists of the following events:
Approval and rejection of a request to create, register, and modify an application.
Approval and rejection of a request to subscribe a package in API Portal.
Group management events
Group management consists of the following events:
Creation, modification, and deletion of a Group object.
Package management events
Package management consists of the following events:
Creation, modification, and deletion of a Package object.
Plan management events
Plan management consists of the following events:
Creation, modification, and deletion of a Plan object.
Policy management
Policy management consists of the following events:
M
Even Header
Creation, modification, and deletion of a global Policy object.

Creation, modification, and deletion of an API level Policy object.
Activation and deactivation of a global policy.
Activation and deactivation of an API level policy.
Promotion management events
Promotion management consists of the following events:
Creation, modification, and deletion of a Stage object.
Promotion of an API stage.
Rollback operation of an API stage.
User management events
User management consists of the following events:
A user logs in or fails to log in to API Gateway.
A user logs out of API Gateway.
Creation, modification, and deletion of a User object.
API Gateway writes the audit logging data to the Audit logs dashboard (in the API
Gateway user interface, go to Analytics > Audit logs). You can view and download audit
logs.
Best Practices for API Gateway Audit Logging

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

You have to configure which events you need to audit for a destination so that API
Gateway logs the auditable events data to the specific destination. You can configure API
Gateway to log the auditable events data to the following destinations:
API Gateway
Elasticsearch
The following events are available for audit log reports:
Access profile management
M
Odd Header
Alias management
API management
Approval management
Group management
Package management
Plan management
Policy management
User management
By default, all of the auditable events are logged into the API Gateway destination.
To configure audit logs

3. Select the required destination to log the auditable events.
4. In the Audit log data section, select the required management areas to monitor, audit,
and report the data.
5. Click Save.
Viewing Audit Logs

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

1. Expand the menu options icon , in the title bar, and select Analytics.
The dashboard displays the API Gateway-wide analytics based on the metrics
monitored.
2. Select Audit logs.
3. In the drop-down list, choose the time interval in which you want to view the data of
auditable events.
The available options are:
Last 2 days
Last 7 days
M
Even Header
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.
Downloading Audit Logs

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

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.
M
Odd Header
Column Detail
creationDate Date and time the event entry was wrien 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).
Service Registries
API Gateway user interface 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.
Overview
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:
M
Even Header
You can publish APIs defined in API Gateway to service registries. This enables
other applications to use the service registry to dynamically locate an API Gateway
instance that provides that API.
You can set an API Gateway route to a service registry endpoint. This enables API
Gateway to use the service registry to dynamically locate an application instance and
route the request to it.
Service Registries supported by API Gateway

API Gateway currently supports the following service registries.
Eureka
Eureka is a REST-based service for locating services for the purpose of load
balancing and failover of middle-tier servers. It has been primarily designed for
applications in the AWS cloud.
Service Consul
Service Consul is a tool for discovering and configuring services in IT infrastructure.
Adding a Service Registry

You must have the Manage service registries functional privilege assigned to perform this
task.
You have to add and configure a service registry in API Gateway before you reference it
in an API. In cluster deployments of API Gateway, you can add a service registry on any
API Gateway instance—other API Gateway instances are synced automatically.
To add and configure a service registry

2. Click Service Registries.
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
M
Odd Header
Field Description
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 The relative path of the service registry discovery

path 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 The relative path of the service registry registration

registration path 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- The relative path of the service registry de-registration

registration path 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 Specifies the time (in seconds) after which a connection

timeout (seconds) aempt times out while communicating with the
service registry.
Read timeout Specifies the time (in seconds) after which a socket
(seconds) read aempt times out while communicating with the
service registry.
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. If you have not configured
an Integration Server keystore the list is empty.
M
Even Header
Field Description
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 seing is applicable only to Eureka service registries.)

The interval at which the API Gateway sends a
heartbeat message to the Eureka server to renew its
leases. Eureka expects clients, such as API Gateway,
to renew the lease by sending heartbeats as per the
heartbeat interval configured in the Eureka server.
Headers
Key An HTTP header key that is included in all the HTTP

requests sent to the service registry.
Value A value for the given HTTP header key.
4. Click Add.
The service registry is added to API Gateway.
Removing a Service Registry

You cannot remove a service registry if any API has been published to it.
You can remove only the non-default service registries that are not used by any API.
You must have the Manage service registries functional privilege assigned to perform
this task.
M
Odd Header
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

2. Click Service Registries.
3. Click in the row that has the service registry that you want to remove.
4. Click Yes to confirm.
The service registry is removed from API Gateway.
M
Even Header
M
Odd Header
Users and Access Profiles
3 Users and Access Profiles

■ Manage Users and Access profiles ........................................................................................... 130
M
Even Header
Users and Access Profiles
Manage Users and Access profiles

You can add and manage user and access profile information from the User
Management page in Integration Cloud.
Users: User personas who can access API Gateway and perform tasks. A predefined user
is an Administrator who has administrator privileges.
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.
User must be associated with atleast one access profile to access and log on to API
Gateway.
For information on managing users and access profiles, see webMethods Integration Cloud
Help.
M
Odd Header
APIs
4 APIs
■ Overview ..................................................................................................................................... 132
■ Creating an API by Importing an API from a File ...................................................................... 135
■ Creating an API by Importing an API from a URL ..................................................................... 135
■ Creating an API from Scratch .................................................................................................... 136
■ API Mashups .............................................................................................................................. 153
■ Viewing API List and API Details ............................................................................................... 160
■ Filtering APIs .............................................................................................................................. 166
■ Activating an API ........................................................................................................................ 166
■ Deactivating an API ................................................................................................................... 167
■ Publishing APIs .......................................................................................................................... 167
■ Unpublishing APIs ...................................................................................................................... 172
■ Modifying API Details ................................................................................................................. 176
■ Updating APIs ............................................................................................................................ 177
■ API Mocking ............................................................................................................................... 181
■ Attaching Documents to an API ................................................................................................. 185
■ SOAP to REST Transformation ................................................................................................. 187
■ Versioning APIs .......................................................................................................................... 195
■ API Scopes ................................................................................................................................ 196
■ Exposing a REST API to Applications ....................................................................................... 205
■ Exposing a SOAP API to Applications ...................................................................................... 206
■ API Grouping .............................................................................................................................. 207
■ API Tagging ................................................................................................................................ 207
■ Exporting APIs ........................................................................................................................... 209
■ Exporting Specifications ............................................................................................................. 210
■ Deleting APIs ............................................................................................................................. 211
■ Example: Managing an API ....................................................................................................... 212
M
Even Header
APIs
Overview
API Gateway provides the ability to view, create, and manage APIs, and publish the
APIs to API Portal for consumption. API administrators and users with the appropriate
functional privileges can use API Gateway to create and manage APIs, and publish the
APIs to API Portal or service registries from where they can be consumed.
API Gateway supports the following API types:
Representational State Transfer (REST) defines a set of architectural principles that
allow accessing and manipulating resources by using capabilities already built into
HTTP, including uniform and predefined set of stateless operations, resources that
are accessible using URIs, and resources that are represented by media types. This
framework provides RESTful APIs based on REST architecture. There are multiple
specification formats for REST APIs. In API Gateway, you would create a REST API
using one of the supported formats: RAML, Swagger 2.0, OpenAPI 3.0 Specification.
The RAML specification is a YAML-based language for the definition of HTTP-
based APIs that embody most or all of the principles of REST. The RAML
specification provides all the information necessary to describe RESTful or
practically-RESTful APIs.
The Swagger 2.0 specification defines a standard, language-agnostic interface
to RESTful APIs. The Swagger specification provides a complete framework
implementation for describing, producing, consuming, and visualizing RESTful
APIs.
The OpenAPI 3.0 Specification (OAS) has a much more modular and reusable
approach for describing and documenting RESTful APIs. OAS enables more
power and versatility when it comes to describing the request and response
messages, as well as providing details on the common components like the
schemas and security definitions
Simple Object Access Protocol (SOAP) defines a communication method for XML-based
message exchange over different transport protocols, such as HTTP and SMTP.
This framework provides SOAP APIs based on Web Services Description Language
(WSDL).
Open Data Protocol (OData) defines a set of best practices for the creation and
consumption of RESTful APIs. It provides a uniform way to describe both data and
the data model. The OData framework provides interoperable OData APIs (with a
RESTful interface) based on OData standards.
Asynchronous APIs
The synchronous and asynchronous nature of an API is a function of the time frame
from the request to the return of data. In the case of synchronous APIs, the expectation
is that there would be an immediate return of data, read from a database, from the
internet, from the disk, or any other I/O source of data. You would use synchronous
APIs where data or service availability, resources and connectivity are high and low
M
Odd Header
APIs
latency is a requirement. The application requests data and waits for it until a value is
returned.
In the case of asynchronous APIs, the availability of a resource, service or data store may
not be immediate. An asynchronous API returns a response acknowledging the receipt
of the request and it continues with the processing of the data till it is done, and returns
a response to the client only when the processing of the data is completed. You would
use asynchronous APIs where data or service availability and connectivity are low or
over-saturated with demand. These APIs may use the callback functionality to send the
callback request to the requester when the requested resource is ready.
Few APIs may take a lot of time to complete their processes, for example, processes such
as purging or archiving of events, and bulk processing operations. In such a scenario, a
time-out may occur for these API invocations as it takes longer time in the synchronous
way where there is a wait period for the return of the data.
Example: Let us consider an example of purging logs.
In the synchronous way, the client application sends a request to the native API to purge
a set of logs with a filter specified. The native API in turn sends out a response with an
acceptance along with a Job ID. The client uses this job ID to send out requests to the
native API to check whether the job is completed. In this case the client may have to
send out multiple requests to check whether the job is done.
To avoid the hassle of multiple calls to the native API and waiting for the job to get
done, you can implement an API to behave asynchronously to avoid multiple checks.
You can implement a REST API with a callback option that can be used to call back the
requestor when the job is done. In this scenario, when the client application sends out a
request to the native API to purge a set of logs with a filter specified, the native API in
turn sends out a response with an acknowledgement of having received the request and
makes a note of the callback request URL that it receives in the request. Now, the client
does not have to send out multiple requests to the native API to check whether the job is
done. Instead once the job is done, the native API uses the callback URL details to send
out a response to the requestor regarding the status of the job being done.
API Gateway provides asynchronous form of API support for REST APIs. API Gateway
provides the capability of defining the callback component with the supported method
parameters while creating a REST API. For details on creating an API with the callback
definition, see “Creating a REST API” on page 142. In addition you can configure API
Gateway to accept the requests from the client that contain the callback request URL and
wrap it with its own URL before routing it to the native API. This lets API Gateway track
the requests that the client sends to the native API and the responses that are sent by the
native API to the client. For details on how to configure the callback processor seings
to enable processing the callback requests, see “Configuring API Callback Processor
Seings” on page 54. When a client sends a request with the callback request URL to the
native API, API Gateway identifies the callback request URL in the incoming request,
depending on the configured callback processor seings wraps the request coming from
the client with its own URL and routes it to the native API. When the requested resource
is ready, the native API sends a request to the callback request URL it has received in the
request it has received from API Gateway. API Gateway then routes this request to the
client. You can configure API Gateway to enforce any of the response processing policies
M
Even Header
APIs
that suits your needs on the immediate responses as well as the callback requests being
sent from the native API to the client.
The callback requests-related event types can be distinguished by a new field with
the value set to true and displayed in the dashboard in the transaction event type. For
a normal request this field is set as false. The following are the field names that are
displayed for various configured destinations:
For API Gateway destination the field name is callbackRequest, which is set to
true.
For Elasticsearch destination the field name is isCallbackRequest, which is set to
true.
For all other destinations, API Portal, Audit Log, CentraSite, Email, and Local log,
the field name is isCallbackRequest, which is wrapped under the customFields
column.
You can create and manage APIs from the Manage APIs page. The page lists all the
APIs, their description, and version number. You can create an API, delete an API, view
API details, activate or deactivate an API, publish or unpublish an API, and view API
analytics from this page.
You can create an API in one of the following ways:
Create an API by importing a definition for an existing API (for example, in Swagger
or RAML format) using an API importer
Create an API from scratch and set its aributes manually
An API importer generates an API from a URL or an input file in one of the supported
formats. For example, the RAML importer installed with API Gateway reads a RAML
file and generates a REST API that the RAML definition describes. The importer also
uploads the RAML file to the API Gateway repository and links the file to the REST API.
The table lists the API types and the file formats required as input to create an API using
an importer.
API type File format
REST RESTful API Modeling Language (RAML)

Yet Another Markup Language (YAML)
JavaScript Object Notation (JSON)
OpenAPI Specification (OAS)
SOAP Web Service Definition Language (WSDL)
OData Entity Data Model (EDMX)
M
Odd Header
APIs
Creating an API by Importing an API from a File

You must have the API Gateway's manage APIs or activate/deactivate APIs functional
privilege assigned to perform this task.
To create an API by importing an API from a file

1. Click APIs in the title navigation bar.
A list of available APIs appears.
2. Click Create API.
3. Select Import API from file.
4. Click Browse to select a file.
5. Select the required file and click Open.
The Swagger parser is a self-contained file with no external references and can be
uploaded as is. If the RESTful API Modeling Language (RAML) file to be imported
contains external references, the entire set of files must be uploaded as a ZIP file with
a structure as referenced by the RAML file.
6. Type a name for the API name in the Name field.
If you provide an API name, this overwrites the API name mentioned in the
uploaded file and the API is displayed with the name provided.
If you do not provide an API name, the API name mentioned in the uploaded file
is picked up and the API is displayed with that name.
If you do not provide an API name and the uploaded file does not have an API
name mentioned, then the API is displayed as Untitled.
7. Select the required type.
The available types are RAML, Swagger, WSDL, and OpenAPI.
8. Provide a version for the API in the Version field.
9. Click Create.
Creating an API by Importing an API from a URL

To create an API by importing an API from a URL

M
Even Header
APIs

3. Select Importing API from URL.
4. Type the URL from where the API is to be imported.
5. Select Protected to make the API a protected API.
6. Type a name for the API name in the Name field.
If you provide an API name, this overwrites the API name mentioned in the
uploaded file and the API is displayed with the name provided.
If you do not provide an API name, the API name mentioned in the uploaded file
is picked up and the API is displayed with that name.
If you do not provide an API name and the uploaded file does not have an API
name mentioned, then the API is displayed as Untitled.
7. Provide a description for the API in the Description field.
8. Select the required type.
The available types are RAML, Swagger, WSDL, OData, and OpenAPI.
9. Provide a version for the API in the Version field.
10. Click Create.
Note: Creating an API by importing swagger files from an HTTPS URL that is
using self-signed certificates may fail. To workaround this, you can set the
system environment variable as: export TRUST_ALL=true, so that the invalid
certificates are ignored. Be aware that seing this variable makes the swagger-
parser ignore all invalid certificates too. So this workaround has to be used
with caution.
Creating an API from Scratch

You can create REST APIs from scratch, meaning that you create the asset and set its
aributes manually.
Overview of Creating a REST API from Scratch

The Create REST API wizard breaks down the task of creating a REST API from scratch
into logical steps. The following figure illustrates the different pages of the wizard.
M
Odd Header
APIs
Basic Information
The Basic Information page includes fields that allow you to identify, categorize, and
group an API.
Technical Information
The Technical Information page includes fields that allow you to define one or more server
URLs for the API. You can also define and include variables in the URLs.
You can also specify parameters for data that must be included in every request to
the API. For example, if you want a specific query parameter to be included in every
request, you can add a parameter of the type Query and specify the value that it must
include.
M
Even Header
APIs
Resources and methods

The Resources and methods page includes fields that allow you to define the API
resources and methods, including callback methods. In this page, you can add all the
resources and their methods that are exposed by the API.
At the resource level, you add a resource by defining the following properties: name,
path, and supported methods. You can additionally add parameters for data that must
be included in every request to that resource. For example, if the methods in a resource
are invoked using URLs that have a query string; you can add a query string parameter
that captures the queries sent by the clients.
At the method level, you identify a method by adding an operation id. In addition, you
can add tags that help you to categorize and search for similar methods. You can also
add parameters at the method level. Similar to the parameters at the API and resource
levels, method parameters enable you to capture and process the data that is sent in
a particular request. In the case of method parameters, the data in the request for that
method is captured and processed.
Method Requests
In the request section of a method, you can define the schema for requests that contain
a JSON or XML payload. As a method can support multiple content types, you need to
add a content type and then define the schema supported by that content type.
You can enter a schema or select an existing schema or global schema that you have
previously added on the Components page, Schemas section. You can also add a sample
for the schema that you have added or selected. These samples can be used for API
mocking. They can also be used by end users to get a beer understanding of the API.
Method Responses
You can define responses for different HTTP status codes. API Gateway gives you the
flexibility to define responses for a status codes series (such as the 2XX series or the 4XX
series) or for specific response codes, such as 201 or 400.
Note: If you have defined the response for a series and specific numbers in that
series, the more specific one is used. Example: If you have added an entry for
2XX and 201, a response with the HTTP status code 200 will be the same as
2XX. However, a response with the HTTP status code 201 will pick the one
that is defined for 201.
For each status code in a method response, you define the following:
Response body: you define the response body using the following fields:
Content Type: You can select from any of the content types.
Schema: You can define a schema if the response contains JSON or XML data.
Sample: The samples are used for API mocking. They can also be used by end
users to get a beer understanding of the API.
M
Odd Header
APIs
Header parameter: You can add a parameter to capture and process a header in the
response sent by the native API.
Links: Links allow the developer of the native API to define the relationship and
traversal mechanism between a response and other operations. You can include
links to other methods that are related to the response. This enables an API client
to dynamically navigate the methods that are exposed by the API. For example,
a method that returns the temperature in Fahrenheit for a given place may also
include links to methods that return: a) the temperature in Centigrade; and b) the
temperature of the place on a given day of the year.
Note: You can define the complete response, or any part of it (response body
schema, header parameter, or link), in the Components page; and reuse it
wherever required by giving a reference.
Method Callbacks
A callback is an asynchronous API request that originates from the API server and
is sent to the client in response to an earlier request sent by that client. APIs can use
callbacks to signal an event of interest and share data related to that event. API clients
that are interested in an event or data related to that event, include a callback URL in
the request they send to the API. For more information about Asynchronous APIs, see “
Asynchronous APIs” on page 132.
To enable API Gateway to process callback messages, you must configure the Callback
processor seings, as explained in “Configuring API Callback Processor Seings” on
page 54.
If your API supports callbacks, you can use API Gateway to process the initial requests,
the callback URLs sent by clients, and the response sent by the API—including the
callback messages. Clients can provide the callback URL to API Gateway in any of the
following ways:
Request header
Query parameter
Request body (if the response body has JSON or XML content)
You must define the relevant parameter to capture the callback URL to process it. API
Gateway can wrap the client callback URLs with its own URL to process these requests if
the callback URL path defined in the following formats. Otherwise, API Gateway sends
the requests received from client as it receives it.
Format Description
{$request.query.param-name} Where param-name is the name of the

query parameter that contains the
callback URL.
M
Even Header
APIs
Format Description
{$request.header.header-name} Where header-name is the name of

the header that contains the callback
URL.
{$request.body#/field-name} Where field-name is a field in the

request body. If the field is an array,
use the syntax {$request.body#/field-
name/arrayIndex}, where arrayIndex is
the index of the callback URL in the
array.
${response.header.header-name} and Where header-name is any of the valid

${response.headers.header-name} header.
${request.query.param-name} Where param-name is the name of the

query parameter that contains the
callback URL.
${response.payload.jsonPath[queryValue]} Where queryValue is a valid JSON

path expression.
${response.payload.xpath[queryValue]} Where queryValue is a valid XPath

path expression.
If you have enabled API Gateway to process callback messages, API Gateway wraps
the callback URL provided by the client and sends an API Gateway URL to the native
API. When the native API invokes the same callback URL, API Gateway processes the
response and applies the policies that you have defined.
API Gateway can apply the following policies on the callback messages: note describing
messages.
Invoke webMethods IS
Response Transformation
Validate API Specification
Data Masking
Log Invocation
Note: These policies are applied to the immediate responses of an API request and
to all its callback requests. These policies are enforced against callback request
payloads.
M
Odd Header
APIs
API mocking
API mocking allows you to simulate a native API that is not available. The mock
response that you define is returned to the client that invokes the API, if the native API
is not available. API mocking is not available while you are creating an API. To use API
mocking, you must edit the API after creating it and enable API mocking.
You must enable API mocking for an API after creating the API. For more information
about API mocking, see “API Mocking” on page 181.
Components
The Components page allows you to add reusable elements that you can use in other
pages of the wizard. You can reference these global elements using the $ref variable.
You can add the following global elements:
Schemas: The schema specified here can be reused in the resource and method
specifications across multiple methods and resources.
Parameters: You can define parameters that can be used as API, resource, and method
parameters.
Headers: You can define parameters that can be reused as header parameters at the
API, method, and response levels.
Examples: You can add examples that can be reused as samples across operations in
the API.
Links: You can define links that can be reused in responses. For more information
about links, see Links within Method Responses above.
Callbacks: You can define callback methods in this page and include them in the
callback section of the methods that use it. For more information about callbacks, see
“ Method Callbacks” on page 139.
Request Bodies: You can define request bodies in this page and reuse them in
methods. A request body includes the content type, a schema, and a sample.
Responses: You can define responses in this page and reuse them in methods. A
response includes the content type, a schema, and a sample. It can also include
header parameters and links.
Documentation
In the view mode, the Documentation page provides the following links:
Links to the Swagger, RAML, and OpenAPI versions of the API on the Integration
Server.
Note: If Cross-Site Request Forgery (CSRF) token is enabled on the Integration

Server, the links to three types of APIs will not work. You must configure
Integration Server to allow these links to work.
M
Even Header
APIs
Links to download the API in the three different formats: Swagger, RAML, and
OpenAPI.
In the edit mode, the Documentation page allows you to add a file that contains any
documentation that you want to include with the API. This file is accessible only from
API Gateway.
Creating a REST API

You can create a REST API from scratch by providing the basic information, technical
information, and defining the resources and methods as required.
To create a REST API from scratch

A list of all existing APIs appears.
3. Select Create from scratch.
4. Click Create.
The Basic information page of the Create REST API wizard appears.
Field Description
Name Name of the API.
Version Version of the API being created.
Maturity state Maturity state of the API.

Available values are: Beta, Deprecated, Experimental,
Production, Test.
The available values depend on the
Maturity states configured in the
apiMaturityStatePossibleValues property under
Administration > Extended settings section.
API grouping Group under which the API would be categorized.
M
Odd Header
APIs
Field Description
Available values are: Finance Banking and Insurance,

Sales and Ordering, Search, and Transportation and
Warehousing.
The available values depend on the groups
configured in the apiGroupingPossibleValues
property under Administration > Extended settings
section.
Tags Keywords for categorizing, identifying, and

organizing APIs. You select from the list of existing
tags or create new tags.
Description Description of the API.
6. Click Continue to provide technical information for this API >.
Note: Click Save to save the API at this stage and close the Create REST API
wizard.
7. Enter the details of the servers that serve the API in the Add server details section.
a. Click Add server and provide a Server URL and Description.
You can include variables in the server URL by enclosing them in curly braces.
These variables are added to the list of variables. However, you have to edit
these variables to add a default value, and optionally one or more values and a
description.
b. Click Add variables and provide the following values:
Name
Description
Default
Value
Note: Click + to add the value that you have entered.
c. Click Add to add the variable.

8. Click Add Parameter and provide the following information to add the API-level
parameters.
M
Even Header
APIs
Field Description
Name Name of the parameter.
Description Description of the parameter.
Type Specifies the parameter type.

Available values: Query-string, Header, Cookie.
Data type Specifies the data type.

Available values: String, Date, Date time, Integer,
Double, Boolean, File.
Required Specifies the parameter is required if selected.
Repeat Select if the input parameter is of type array.
Value Specifies the possible values.
Note: You need to define parameters only for data that you want API Gateway to
process.
9. Type a Service registry display name.

By default, the API will be displayed in service registries with the name:
APIName_Version. If you want the API to be displayed in the service registries with a
different name, you can type the name here.
10. Click Continue to provide Resource and methods for this API>.
wizard.
11. Add resources to the API using the Resources and methods page:
a. Click Add Resources and provide the following information:
Field Description
Resource name Name of the resource.

This is the display name of the resource and
resource path is used for execution.
Resource path Specifies the path of the resource.
M
Odd Header
APIs
Field Description
The resource path should contain a "/".
Description Description of the resource.
Supported methods Select the methods that are supported by the API:
GET, HEAD, POST, PUT, DELETE, PATCH.
b. Click Add.
The resource is added. You can multiple resources, if required.
c. Add Tags.
d. Click Add Resource Parameter and provide the following information:
Field Description
Reference If you want to reuse a global parameter defined on the

Components page, select the parameter from the drop-
down list.
Description Brief description of the parameter.

Available values: Path, Header, Query-string, Cookie.

Available values: String, Date, Date time, Integer, Double,
Boolean, File.
Value Specifies the possible values for the parameter.
e. Click + Add to add the resource parameter.

12. For each supported method that you have added for a resource, enter the following
information:
M
Even Header
APIs
a. Common information:
Field Description
Description Type a description for the operation.
OperationId Type an operation Id.
Tags Type or select the keywords that you want to add to

the operation.
b. Method parameters
Field Description
Reference If you want to reuse a global parameter defined on the

Components page, select the parameter from the drop-
down list.

Available values: Query-string, Header, Cookie.

Available values: String, Date, Date time, Integer, Double,
Boolean, File.
Required Specifies the parameter is required, if selected.
c. Requests: You can select an existing global request defined on the Components
page or specify a new request. To enter a new request, select New request and
provide the following information:
To add a new request that has to be processed, click Add Request + and provide
the following information:
M
Odd Header
APIs
Content type: Select one and click Add.

Schema: Type a schema in the text box or select an existing schema from the
Select a Schema list. You can also click Add global schema and create a new
global schema on the Components page. After creating the global schema you
can select it from the Select a Schema list.
Sample: Type a sample for selected schema. This sample can be used for API
mocking, if required.
To use an existing global request to process a request, select Global request and
Name:
Reference: select one and click Add.
d. Responses: First, add a status code using the Status Code drop-down list. Next,
click on the status code to select it. For the selected status code, you can select
an existing global response defined on the Components page or enter a new
response. To enter a new response, select New response and define the response
by adding a schema and a sample for the response body, header parameters, and
links.
Note: You can also define the response for an HTTP status code series, such as
2** or 4**.
To define a new response for the selected status code, click Add response + and
Content type: select one and click Add.
Schema: Type a schema in the text box or select an existing schema from the
Select a Schema list. You can also click Add global schema and create a new
global schema on the Components page. After creating the global schema you
can select it from the Select a Schema list.
Sample: Type a sample for selected schema. This sample can be used for API
mocking, if required.
To use an existing global response, select Global response and provide the
following information:
Name: Name of the response.
Reference: select one and click Add.
To add a header parameter, click + Add header parameter and enter the following
information to add a header parameter:
Field Description
M
Even Header
APIs
Field Description
Reference If you want to reuse a global parameter defined on

the Components page, select the parameter from the
drop-down list.

Available values: Header.

Double, Boolean, File.
Click + in the Value text box to add a value to the list, and click Add to add the
header.
To add a link, click + Add links and enter the following information to add a link:
Name: Name of the link.
Description: Description for the link.
Link: You can add a new link or select an existing global link that is defined
on the Components page.
To add a new link, select New link and enter the following information:
Type: Select OperationId for local operations only. OperationRef can be used
for both local and external operations.
Value: If Type is OperationRef, provide a reference to the target operation
using the JSON Reference syntax (using by the $ref keyword); and if the
Type is OperationId provide the OperationId of the target operation.
Parameters: Specify the parameters of the target operation that are
required to follow the link. Enter a Name and Value, and click Add.
Request body: Enter a request body only if the target operation has a body.
Define the contents of the body of the target operation.
M
Odd Header
APIs
To include an existing global link, select Global link and then select an existing
global link from the Reference drop-down list.
e. Callbacks: You can add the callbacks that are supported by the method. You can
add new callbacks and select existing global callbacks.
Note: For more information about using callbacks to develop asynchronous

APIs, see Asynchronous APIs in “Overview” on page 132. For more
information on defining and using callbacks in API Gateway, see “
Overview of Creating a REST API from Scratch” on page 136.
To specify a new callback, click + Add callbacks and define the callback:
Name: A name for the callback resource.
Click + Add resources and provide details of the API that serves as the callback
API.
Note: The user interface and procedure for defining a callback is similar to
defining a resource and methods within the resource.
To include a global callback defined on the Components page, provide the

Name: Name of the callback resource.
Reference: If you want to reuse a global callback defined on the Components
page, select the callback from the drop-down list and click Add.
13. Click Continue to provide Mocking information for this API>.
wizard.
The API mocking page appears. API mocking is not enabled for a new API: You
must edit the API and enable API mocking after creating the API.
14. Click Continue to define API components for this API>.
Alternatively, you can click Components.
wizard.
15. Define the reusable elements that you want to reuse in other pages of the Create
REST API wizard.
An API may have several elements that are common across resources and methods,
such as schemas for response bodies. You can place such common elements in the
Components section and reference them using the $ref alias.
a. In the Schemas section, click + Add schema and provide the following information:
M
Even Header
APIs
Field Description
Name Name of the schema.
Schema type Specifies the schema type.

Available types: Inline schema and External schema.
Value Specifies the value for the schema type selected.

For an inline schema, type the request and response
values.
For an external schema, click Browse to upload a
schema.
Click + Add to add the schema component.

b. In the Parameters section, click + Add parameter and provide the following
information:
Field Description

Available values: Path, Query-string, Header, and
Cookie.

Double, Boolean, and File.
Click + Add to add the parameter component.

c. In the Headers section, click + Add header and provide the following information:
M
Odd Header
APIs
Field Description
Name Name of the header.
Description Description of the header.
Type Specifies the header type. This is fixed as Header for

headers.

Double, Boolean, and File.
Required Specifies the header is required if selected.
Value Specifies the possible values for the header.
Click + Add to add the header component.

d. In the Examples section, click + Add examples and provide the following
information:
Field Description
Name Name of the example.
Summary Description of the example.
Value The content of the example.
Click + Add to add the example component.

e. In the Links section, click + Add links and provide the following information:
Field Description
Name Name of the link.
Description Description of the link.
M
Even Header
APIs
Field Description
Type Specifies the link type: OperationId or OperationRef.
Value Path to the target operation or a reference to the

target operation.
Parameter name Name of the parameter that needs to be passed as a

parameter to the target operation.
Parameter value Value for the parameter. Click + Add to add the
parameter. You can additional parameters if
required.
Request body Payload of the request sent to the target operation.
Click Add to add the link component.

f. In the Callbacks section, click + Add callback and provide the following
information:
a. Type a name for the callback.
b. Click + Add resources.
c. Type the Callback path.
d. Select the supported methods.
e. Click Add.
f. For each method that you have just added, complete the next two steps.
g. Click + Add Resource Parameter and add the required resource parameters. The
procedure for adding resource parameters is given in Step 11d.
h. Define the selected methods. The procedure for defining methods is given in
Step 12.
g. In the Request Bodies section, click + Add request and provide the following
information:
Field Description
Name Name of the request.
Content type Select a content type from the list.
Schema You can also select an existing schema.
M
Odd Header
APIs
Field Description
Sample Type a sample of the schema.
Click Add to add the request component.

h. In the Responses section, click + Add Response and provide the following
information:
Field Description
Name Name of the response.
Content type Click Add.
Schema You can also select an existing schema.
Sample Type a sample of the schema.
Header Parameter Click + Add Header Parameter and provide the

required information. Then, click + Add to add the
header parameter.
Links Click + Add Links and provide the required

information. Then, click Add to add the link.
Click Add to add the response component.

16. Click Continue to provide API documents for this API>.
wizard.
The Documentation page appears.

17. Type a display name and click Browse to select a file.
18. Click + Add to upload the file and add a new row.
19. Click Save to save your changes and create the API.
API Mashups
Overview
Servers that provide an API may expose a vast set of functionality. However, each
individual service in the API usually provides a very specific functionality. While this
M
Even Header
APIs
is usually effective, sometimes it is useful or required to consolidate a few services

and expose them as a single service. In other situations, you might want to extend a
service with the functionality provided by an external API. API mashups address these
requirements for grouping services and exposing them as a single service.
Note: Currently, API Gateway supports API mashups for REST APIs only: You can
define a mashup only in a REST API and only REST APIs can be included in
the mashup.
Usage scenario
Assume an API that provides information about courses offered by different universities
in a given location. This API provides a service that returns the list of universities for a
given course name and postal code. This service could be:
GET /universities?course=medicine&postalcode=600012
The provider of the API wants to extend this API for use in mobile applications that
have access to users’ location. As mobile applications can access a user’s location in
terms of longitude and latitude, this involves first retrieving the postal code for the
users’ current location and then passing that information to the existing API.
Suppose there is a publically available API that returns the postal code based on
longitude and latitude values. This service could be:
GET /postalcode?lat=331&long=22324321
If this public API meets other requirements, such as security, performance, and usage
limits, it can be utilized to deliver the required functionality.
Using an API mashup, you can create and expose a single service that calls both services:
the external service that returns the postal code and the existing service that provides the
list of universities. The resulting service could be:
GET /universities?course=medicine&lat=331&long=22324321
Key Features of a REST API Mashup

An API mashup allows you to orchestrate multiple resources and methods and
expose the behavior as a single service. In a regular method that is not a mashup,
API Gateway applies all the enforced policies and then routes the request to the
native endpoint. In the case of a mashup, API Gateway still applies all the enforced
policies in the request flow till routing; but thereafter, it starts the orchestration flow
defined in the mashup. After the orchestration flow ends, all the policies defined for
that method are applied in the response flow—in the same way as a regular method.
API mashups are defined at the method level. You can edit any REST API and define
a mashup for one or more methods within it.
You can include any REST API defined within API Gateway in the mashup.
The entire framework that API Gateway provides to a regular REST API method is
available to an API mashup method. Therefore, you can utilize query parameters,
path parameters, aliases, variables, payload transformations using XSLT transforms,
transformations using webMethods IS services, and custom pipeline variables.
M
Odd Header
APIs
Considerations for Creating an API Mashup

By default, the policies of an API that is participating in an API mashup are not
enforced when it is invoked within the API mashup. However, if you select the
Should execute Outbound policies option, the outbound security policies of the
participating API are enforced in the context of the API mashup.
The following are specific to a mashup step and are not automatically passed from
one step to another:
Headers
Query parameters
Path parameters
Payload
However, you can add parameters in a mashup step to access data from any of the
previous steps or another source.
An exception to this rule is the first step (the first participating service) in a mashup,
which receives the complete request sent by the client.
Structure of an API Mashup

An API mashup consists of one or more mashup steps, and each step invokes an
API. A mashup step defines the request for the API that it invokes. A step can use the
data objects provided by API Gateway to access data in the initial request sent to the
operation that has the mashup and any of the previous steps.
The following table summarizes the data objects and variables that are available in API
Gateway.
Object/Variable Type Possible values
paramStage request
response
paramType payload or body
headers
query
path
httpMethod
statusCode
statusMessage
M
Even Header
APIs
Object/Variable Type Possible values
queryType xpath
jsonPath
regex
The following data objects are available to a mashup step:

${paramStage.paramType}
You can use this syntax to access the following string variables: path,
statusCode, statusMessage, httpMethod. Examples: ${request.path},
${response.statusCode}
${paramStage.paramType.paramName}
You can use this syntax to access map types, such as query, headers, and path.
Example: ${request.query.var1}, ${response.header.Content-Type},
${request.path.name}.
${paramStage.paramType.queryType[queryValue]}
This syntax can be used to query a paramType. Examples:

${request.payload.xpath[//ns:emp/ns:empName]}
Where "//ns:emp/ns:empName" is the XPath to be applied on the payload if

contentType is "application/xml", "text/xml", or "text/html".
${response.payload.jsonPath[$.cardDetails.number]}
Where "$.cardDetails.number" is the jsonPath to be applied on payload if

contentType is "application/json" or "application/json/badgerfish".
${request.payload.regex[[0-9]+]}
Where "[0-9]+" is the regular expression to be applied on the payload if
contentType is "text/plain".
Note: While xpath and jsonPath are applicable only to payload, regEx can be
used with both payload and path.
${paramStage[stepName].paramType.queryType[queryValue]}
You can use this syntax to access data from any of the
previous steps. For example, you can use the following
syntax to access the payload of the step named createAPI:
${response[createAPI].payload.jsonPath[$.apiResponse.api.id]}.
You can define your own variables using the Custom Pipeline variables field:
Examples: ${key}, ${value}. The custom pipeline variables that you define are available
in subsequent steps.
M
Odd Header
APIs
Creating an API Mashup

You can create a mashup in an existing REST API.
To create a mashup in a REST API

A list of all registered APIs appears.
2. Click the required API.
The API details page appears.
3. Click Edit.
4. Click Mashups.
The Mashups tab appears. It displays the resources in the API and their methods on
the left and an empty (Default routing) routing diagram.
Note: If the API does not have any mashup, the Mashup tab displays the list of
resources only in the Edit mode; the tab is empty in the view mode.
5. In the List of resources, click the resource in which you want to include the mashup.
The resource tab expands and the methods included in the resource are displayed.
6. Click the toggle buon to enable the method in which you want to create the
mashup.
Note: If you use the toggle buon and disable a method that has a mashup, the
mashup definition for that method is immediately cleared.
7. Click Add invoke.

The Mashup Routing panel appears on the right.
8. Provide a Mashup step name that is unique.
9. To select the API Endpoint that you want to invoke in the mashup step, provide the
following fields.
Note: To provide the API Endpoint, you can type a few leers and select from the
autocomplete drop-down list.
a. Type or select the API Gateway API.

b. Type or select the Resource.
c. Type or select the Method.
d. Select Should execute Outbound policies if you want the outbound security policies
of the participating API to be enforced in the context of an API mashup.
M
Even Header
APIs
10. Provide the Headers as follows:

a. Select Use incoming Headers to use the headers in the incoming request.
b. Additionally, you can add custom headers in the Custom Headers section as
follows:
a. Type or select the Header Name.
b. Type or select the Header Value.
c. Click Add.
Note: You can access values from previous steps and other data using the
variable and alias framework provided by API Gateway. For more
information, see “Structure of an API Mashup” on page 155.
11. Provide the Query Parameters as follows:

a. Type or select the Query Parameter Name.
b. Type or select the Query Parameter Value.
c. Click Add.
12. Provide the Path Parameters as follows:
a. Type or select the Path Parameter Name.
b. Type or select the Path Parameter Value.
c. Click Add.
13. Enter the Payload as follows:
Note: You can access the payload from previous steps and other data using
the variable and alias framework provided by API Gateway. For more
a. Type the Payload.

b. To include an advanced payload transformation, click Add xslt document.
c. Select an XSLT file.
d. Add an XSLT Feature Name.
M
Odd Header
APIs
e. Add a value for the feature in XSLT Feature value.

f. Click Add.
g. To add an XSLT transformation alias, click XSLT transformation alias.
h. Select an XSLT transformation alias from the drop-down list.
i. Click Add.
14. Provide an Advanced transformation, if required.
Note: For more information on defining an advanced transformation using the

webMethods IS request processing policy, see “Invoke webMethods IS” on
page 259.
a. Click Add webMethods IS service.

b. Type the path to a webMethods IS service.
c. Select a Run As User from the drop-down list.
d. Deselect Comply to IS Spec if required.
e. Click Add.
f. Select a webMethods IS Service Alias from the drop-down list.
15. Enter the Transformation metadata, if required.
a. Type a Namespace Prefix.
b. Type a Namespace URI.
16. Provide the Custom Pipeline variables, if required.
You can use custom pipeline variables to hold values that need to be used in another
step of the API mashup. For more information, see “Structure of an API Mashup” on
page 155.
a. Type a Name.
b. Type a Value.
c. Click Add.
17. Click Save.
The mashup is created for the selected method.
Note: You must activate the API to make the mashup available to client applications.
For more information about activating an API, see “Activating an API” on
page 166.
M
Even Header
APIs
Viewing API List and API Details

You can view the list of registered APIs, activate, delete, or view analytics of a specific
API in the Manage APIs page. In addition, you can view API details, modify API details,
activate and deactivate an API in the API details page.
To view API list and API details

A list of all registered APIs appears. You can also perform the following operations
in the APIs page:
Filter APIs by Type or Activation status.
Activate an API by clicking that denotes an inactive state.
Once an API is activated, the Gateway endpoint is available which can be used
by the consumers of this API.
Deactivate an API by clicking the status icon that denotes an active state.
Delete an API by clicking the Delete icon.
View API analytics by clicking the Analytics icon.
Publish or Unpublish an API by clicking Publish and the Unpublish icons
respectively.
2. Click any API to view API details.
The API details page displays the basic information, technical information, resources
and methods, and specification for the selected API.
REST API Details

The REST framework enables you to model APIs conforming to the (Resource Oriented
Architecture) ROA design. For example, you might model an API that serves to expose
the web service data and functionality as a collection of resources. Each resource is
accessible with unique Uniform Resource Identifiers (URLs). In your API, you expose
a set of HTTP operations (methods) to perform on a specific resource and capture the
request and response messages and status codes that are unique to the HTTP method
and linked within the specific resource of the API.
The API details view for a REST API displays the details of the API such as Basic and
Technical information, Resources and methods, API mocking details, and specifications.
You can also view the scopes associated, policies enforced, registered applications and
the API-specific analytics.
The table lists the API details displayed for the API
M
Odd Header
APIs
Field Description
Basic information Displays the information about the API, such as

Name, Version, Owner of the API, status of the API
whether its is Active or Inactive, the maturity state of
the API, the date on which the API was created and a
brief description of the API.
Technical information Displays the native endpoints of the API.
Resources and methods Displays a list of resources or methods available in

the API sorted by resource/pathname.
The list of resources are displayed in sorted order
of the path names. Click each resource to view
the corresponding HTTP methods, along with a
summary. Below each of these methods, details such
as parameters and response codes are displayed.
API mocking Details are visible only when API mocking is

enabled.
Displays a list of mocked responses for the
operations in the API, custom IS service list and
conditions along with its mocked response.
Components Displays the schemas defined at the API level.
Documentation Displays the definition of the API in different

formats.
Various tabs displayed in the API details page display the following details:
The Scopes tab lists the scopes available for the API.
The Policies tab displays the policies enforced for the API.
The Mashups tab displays the mashups defined in the API.
The Applications tab displays all the applications registered with the API.
The Analytics tab displays the API-specific analytics for the time interval selected.
You can perform the following operations from the API details page:
You can enable API mocking by clicking the Enable mocking buon. If API mocking
is enabled, you can disable it by clicking the Disable mocking buon. This option is
available when the API is in the deactivated state.
M
Even Header
APIs
You can update an API by importing from file or from URL by clicking the Update
buon. This option is available when the API is in the deactivated state.
You can create a new version of the API by clicking the Create new version buon.
You can modify details of an API by clicking the Edit buon. This option is available
when the API is in the deactivated state.
You can activate an API by clicking the Activate buon. If the API is already
activated, you can deactivate it by clicking the Deactivate buon.
SOAP API Details

The API details view for a SOAP API displays the details of the API such as Basic and
Technical information, Operations available, REST transformation details, API mocking
details, and specifications. You can also view the scopes associated, policies enforced,
registered applications and the API-specific analytics.
The table lists the API details displayed for the API
Field Description
Basic Displays the information about the API, such as Name,

information Version, Owner of the API, status of the API whether its is
Active or Inactive, the maturity state of the API, the date
on which the API was created and a brief description of the
API.
Technical Displays the native endpoints of the API.

information
Operations Displays a list of operations available in the API and they

are sorted alphabetically.
Operations are displayed along with their type of binding
(SOAP 11 , SOAP 12, and other HTTP methods). Click each
method to view details such as input, output, and fault
messages.
REST Displays a list of operations exposed as REST resources and

transformation they are sorted alphabetically.
Operations are displayed along with their type of binding.
Click each method to view details such as input, output, and
fault messages.
API mocking Details are visible only when API mocking is enabled.
M
Odd Header
APIs
Field Description
Displays a list of mocked responses for the operations in

the API, custom IS service list and conditions along with its
mocked response that contains the status code and mock
payload details.
Specifications Displays a list of specifications for the API.
The Scopes tab lists the scopes available for the API.
You can enable API mocking by clicking the Enable mocking buon. If API mocking
is enabled, you can disable it by clicking the Disable mocking buon. This option is
available when the API is in the deactivated state.
You can update an API by importing from file or from URL by clicking the Update
buon. This option is available when the API is in the deactivated state.
when the API is in the deactivated state.
OData API Details

Open Data Protocol (OData) enables the creation of REST-based APIs, which allow
resources to be exposed as endpoints and identified using the Uniform Resource
Identifiers (URIs). In general, OData is represented by an abstract data model called
Entity Data Model (EDM). This Entity Data Model allows Web clients to publish and edit
REST services and their resources using simple HTTP messages. OData leverages the
principles of HTTP, REST and ATOM, and combines the simplicity of REST and SOAP
metadata definitions to describe service interfaces, data models, and semantics.
API Gateway supports OData V4 and V2 services.
The API details view for a OData API displays the details of the API such as Basic and
Technical information, OData entity sets, singletons, function imports, actions imports
and specifications. You can also view the policies enforced, registered applications and
the API-specific analytics.
M
Even Header
APIs
The API Gateway UI exposes only OData navigation properties to visualize the resource
path structure of OData APIs. Any other OData property is not displayed.
Note: API Gateway does not support the querying of Derived Entity Types. This
includes the following operations:
Requesting a Derived Entity
Requesting a Derived Entity Collection
Filter on Derived Type
Operations on Derived Types are rejected by API Gateway.
The table lists the API details displayed for the API.
Field Description
Basic information Displays the information about the API, such as

Name, Version, status of the API whether its is
Active or Inactive, the date on which the API was
created, and a brief description of the API.
Technical information Displays base URL of the API and the OData version
supported
OData entity sets Displays a list of OData entity sets. An entity set
element represents a single entity or a collection of
entities of a specific entity type in the data model
The list of entity sets is sorted alphabetically. Click
each entity set to view the resource path, entity type,
resource parameter details, and the corresponding
HTTP methods.
The entity types are structured records consisting
of named and typed properties and key properties
whose values uniquely identify one instance from
another.
OData singletons Displays a list of OData singletons. Singletons are

single entities which are accessed as children of the
entity container.
The list of singletons is sorted alphabetically. Click
each singleton to view the resource path, entity
type, the corresponding HTTP methods, and the
navigation properties that allow navigation from an
entity to related entities.
M
Odd Header
APIs
Field Description
The OData navigation property has an impact on the

resource structure. This property is represented as
an OData Resource and denoted as OData Navigation
properties inside the OData Resources profile. There
is no restriction to the number of levels you can drill
down.
OData function imports Displays a list of OData function imports. The

Function Import element represents a Function in an
entity model.
The list of OData function imports is sorted
alphabetically. Click each function import to view
the resource path, entity type, and the corresponding
HTTP methods.
OData action imports Displays a list of OData action imports. The Action
Import element represents an Action in an entity
model.
The list of OData action imports is sorted
alphabetically. Click each action import to view the
resource path, entity type, and the corresponding
HTTP methods.
Specifications Displays a list of specifications for the API.

The metadata document. The metadata document
describes the Entity Data Model that is, the structure
and organization of the OData service resources)
exposed as HTTP endpoints by that particular
service. This document describes the entity types,
entity sets, functions and actions.
You can update an API by importing from URL by clicking the Update buon. This
option is available when the API is in the deactivated state.
M
Even Header
APIs
when the API is in the deactivated state. Only the following properties of an OData
API can be modified:
Name
Description
Version
API group
Maturity state
For updating the OData entity sets, singletons, function imports and action imports a
new import has to be performed.
Filtering APIs
You can filter APIs based on the API type or the activation status of the API.
To filter APIs
2. In the Add Filter pane, select REST, SOAP, OData or all to filter APIs by type.
3. In the Add Filter pane, select Active and/or Inactive to filter APIs by their activation
status.
4. Click Apply filter.
The filtered list of APIs is displayed. You can click Reset to reset the values to the
original values.
Activating an API
You can activate an API in the Manage APIs page. Alternatively you can also activate the
API from the API Details page.
You must have the Activate/Deactivate APIs functional privilege assigned to perform
this task.
To activate an API
M
Odd Header
APIs
2. Click the toggle buon, in the corresponding column of the API to be activated, to
change the status to to activate the API.
The API is now activated. The Gateway endpoint is now available, which can be
used by the consumers of this API. You can now publish the API to the required
destination and expose the API for consumption by the consumers.
You can modify API details or update the API, except the name and version of the
API, when the API is in the active state. Active APIs are replaced during deployment
with zero downtime and do not break ongoing requests. The updated APIs do not
become effective for ongoing requests.
Note: If there is an error while saving after updating an active API, the API
becomes inactive but the changes are saved.
Deactivating an API
You can deactivate an API in the Manage APIs page. Alternatively you can also
deactivate the API from the API Details page.
You must have the Activate/Deactivate APIs functional privilege assigned to perform
this task.
To deactivate an API
2. Click the toggle buon, in the corresponding column of the API to be deactivated, to
change the status to to deactivate the API
The API is now deactivated. The API is no more available to be consumed by
consumers.
Publishing APIs
You can publish an API to two types of destinations: API Portal and Service Registries.
Publishing APIs to API Portal

Publishing an API to API Portal sends the SOAP and REST APIs to API Portal on which
they are exposed for testing and user consumption.
M
Even Header
APIs
The process of publishing an API to API Portal is initiated from API Gateway and is
carried out on the API Portal server.
Doing this involves the following high-level steps:
Step 1: You initiate the publish process by selecting the API to be published, specify
the API endpoints to be visible to the consumers, and the API Portal communities in
which the API is to be published.
Step 2: API Gateway publishes the API to each of the specified API Portal
communities.
Step 3: During bulk publishing of APIs, the process continues even if API Gateway
encounters a failure with API Portal.
When publishing an API to the API Portal destination, keep the following points in
mind:
The API Portal destination must be configured in API Gateway.
You must have the Publish to API Portal functional privilege.
You cannot publish an API if it is in inactive state. You have to activate the API
before publishing it.
Publishing a Single API to API Portal

Pre-requisites:
You must have the Publish to API Portal functional privilege assigned to perform this
task.
To publish an API to API Portal

A list of all APIs appears.
2. Click the Publish icon for the API that you want to publish.
3. Select the API endpoints that need to be visible to the consumers.
At least one endpoint should be selected before publishing the API.
4. Select the API type if you want to publish a REST-enabled SOAP API.
When the REST transformation is enabled for a SOAP API in API Gateway, you can
publish the REST-enabled SOAP API to API Portal in one of the following ways:
Publish as REST: Default. The API is published as a REST API to API Portal.
The REST resources and methods which correspond to the transformed SOAP
operations are also published to API Portal.
Publish as SOAP: The API is published as a SOAP API with the SOAP operations
to API Portal.
M
Odd Header
APIs
Publish as REST and SOAP: When both the options are selected, the API is
published as a REST API as well as a SOAP API in API Portal and marked as a
HYBRID API.
Note: The Publish as option is available only if the REST transformation is

enabled for the SOAP API.
5. Select the communities to which the API needs to be published.

By default, an API is published to the Public Community of API Portal.
6. Click Publish.
The API along with the selected endpoints is published to API Portal and available
for the consumers to consume it.
A REST-enabled SOAP API is published to API Portal based on the selected API
type:
REST API. The API Details view displays the published API as a REST API with
the defined REST resources and methods.
SOAP API. The API Details view displays the published API as a SOAP API with
the defined SOAP operations.
HYBRID API. The API Details view, by default, displays the published API as a
REST API with the REST resources and methods. There is an option SOAP that
can be selected to display the published API as a SOAP API with the SOAP
operations.
Once an API is published, the Publish icon changes to Republish icon.
You can unpublish an API once it is published by clicking the Unpublish icon.
Publishing Multiple APIs to API Portal in a Single Operation

Pre-requisites:
task.
You can bulk publish APIs to API Portal.
To publish multiple APIs to API Portal in a single operation

2. Select the APIs that you want to publish.
By default, all the respective API endpoints are internally selected to be visible to the
consumers.
3. In the Menu icon, click Publish.
M
Even Header
APIs
4. Select the communities to which the APIs have to be published.

By default, the APIs are published to the Public Community of API Portal.
5. Click Publish.
The APIs along with their associated endpoints are published to API Portal and
available for the consumers to consume.
If you have selected several APIs where one or more of them are REST-enabled
SOAP APIs in API Gateway, then these SOAP APIs are published as REST APIs
along with their specific REST endpoints in API Portal.
6. Examine the Publish APIs report window and check for any errors that occurred
during the publishing process.
The Publish APIs report window displays the following information:
Parameter Description
Name The name of the published API.
Status The status of the publishing process. The

available values are:
Success
Failure
Description A descriptive information if the API

publishing process fails or if a warning
occurs.
API Gateway writes these results to the Audit logs dashboard, so you can view them
later.
7. Click Download the detailed report here to download the detailed report as an HTML
file.
Publishing APIs to Service Registries

Publishing an API to a service registry enables applications to dynamically locate an API
Gateway instance that can process that API.
When publishing an API to a service registry, keep the following points in mind:
Before you publish an API to a service registry destination, you must add the service
registry to the API Gateway instance from where you want to publish.
You must have the Publish API to service registry functional privilege to publish APIs to
a service registry.
M
Odd Header
APIs
You can publish only active APIs. You cannot publish APIs that are in the inactivate
state.
An API that is published to a service registry:
Is automatically de-registered from the service registry if the API is deactivated
in API Gateway. When the API is activated again, it is automatically registered
on the same service registry.
Is automatically de-registered from the service registry if the API Gateway
instance from where it was registered goes down. When the API Gateway
instance comes up again, the API is registered on the same service registry.
In a cluster of API Gateway nodes, only the API Gateway instance from where you
publish an API is added to the service registry. You have to separately publish the
API from each API Gateway instance that the service registry can use for an API.
Note: Similarly, you have to separately unpublish the API from each API
Gateway instance from where you want to unpublish the API.
If a load balancer has been configured for the API Gateway cluster, APIs from all
instances are registered using the load balancer URL.
Publishing a Single API to Service Registries

Pre-requisites:
You must have the Publish API to service registry functional privilege assigned to perform
this task.
To publish an API to service registries

The list of APIs defined in API Gateway appears.
2. Click the Publish icon for the API that you want to publish.
3. Select Service Registries.
The list of service registries that have been added to API Gateway is displayed.
4. Select the service registry to which you want to publish the API.
The list of endpoints in the selected API are displayed.
5. Select the endpoints that you want to publish to the selected service registry.
6. Repeat the previous two steps to publish the API to additional service registries.
7. Click Publish.
You can unpublish a published API by clicking the Unpublish icon.
M
Even Header
APIs
Publishing Multiple APIs to Service Registries in a Single Operation

Pre-requisites:
this task.
Note: When you publish multiple APIs to one or more service registries in a single
operation, all endpoints in the APIs are published. To selectively publish
endpoints within an API, you must publish the API separately as a single API.
To publish multiple APIs to service registries in a single operation

The list of APIs defined in API Gateway appears.
2. Select the APIs that you want to publish.
3. On the menu, click Publish.
4. Select Service Registries.
The list of service registries that have been added to API Gateway is displayed.
5. Select the service registry to which you want to publish the API and click Publish.
You can unpublish a published API by clicking the Unpublish icon.
Unpublishing APIs
You can manually unpublish APIs that you had previously published to an API Portal or
to one or more service registries.
Unpublishing APIs from API Portal

After you publish an API to API Portal, the API remains published and available on API
Portal for consumption until you manually unpublish the API.
You can unpublish a SOAP or REST API from API Portal to suspend its interaction,
testing, and user consumption in API Portal.
Unpublishing a Single API from API Portal

Pre-requisites:
task.
M
Odd Header
APIs
To unpublish an API from API Portal

2. Click the Unpublish icon for the API that you want to unpublish.
The Unpublish API dialog box is displayed.
3. Select API Portal in Destination.
4. Select Force unpublish to ???
The API is unpublished from the API Portal destination. The API is no longer
available on API Portal for testing and user consumption.
Once an API is unpublished, the Republish icon changes to Publish icon.
You can publish an API once it is unpublished by clicking the Publish icon.
Unpublishing Multiple APIs from API Portal in a Single Operation

Pre-requisites:
task.
You can bulk unpublish APIs from API Portal.
To unpublish multiple APIs from API Portal in a single operation

2. Select the APIs that you want to unpublish.
3. In the Menu icon, click Unpublish.
The selected APIs are unpublished from API Portal.
5. Examine the Unpublish APIs report window and check for any errors that occurred
during the unpublishing process.
The Unpublish APIs report window displays the following information:
Name The name of the unpublished API.
M
Even Header
APIs
Status The status of the unpublishing process.

Success
Failure

unpublishing process fails or if a warning
occurs.
later.
file.
Unpublishing APIs from a Service Registry

You can manually unpublish APIs that you had previously published on service
registries.
You must consider the following points before unpublishing an API from a service
registry:
You must have the Publish API to service registry functional privilege to unpublish APIs
from a service registry.
There is no option to unpublish individual endpoints. When you manually
unpublish an API, all the endpoints in that API are unpublished from the selected
service registries.
As both—API publishing to service registries and API unpublishing to service
registries—are specific to the current API Gateway instance, APIs are unpublished
only for the API Gateway instance from where you unpublish. Therefore, if the same
API was published from other instances of API Gateway, it continues to be available
on the service registries from those API Gateway instances.
APIs may also get unpublished automatically from service registries, as described
below.
Automatic Unpublishing of APIs

API Gateway automatically, but temporarily unpublishes an API in the following
situations:
When you deactivate an API after publishing it to a service registry.
M
Odd Header
APIs
Note: When you reactivate the API, the temporarily unpublished endpoints are
published again to the original service registries.
When you disable or delete an API Gateway port that has endpoints that have been
published to a service registry.
Note: When you enable or add back the port again, the temporarily unpublished
endpoints are published again to the original service registries.
Unpublishing a Single API from Service Registries

Pre-requisites:
this task.
To unpublish an API from Service Registries

2. Click the Unpublish icon for the API that you want to unpublish.
The Unpublish API dialog box is displayed.
3. Select Service registries in Destination.
The list of service registries to which the API was published is displayed.
4. Select the service registries from which you want to unpublish the API.
5. Select Force unpublish to mark the API as unpublished in API Gateway even if the
unpublish fails on the selected service registries.
The API is unpublished from the selected service registries. The API is no longer
available on selected service registries for testing and user consumption.
Once an API is unpublished, the Republish icon changes to Publish icon.
Unpublishing Multiple APIs from Service Registries in a Single Operation

Pre-requisites:
this task.
You can bulk unpublish APIs from one or more service registries.
To unpublish multiple APIs from service registries in a single operation

M
Even Header
APIs
2. Select the APIs that you want to unpublish.

3. In the Menu icon, click Unpublish.
4. Select Service registries in Destination.
The list of service registries to which the APIs were published is displayed.
5. Select the service registries from which you want to unpublish the selected APIs.
6. Select Force unpublish to mark the APIs as unpublished in API Gateway even if the
unpublish fails on the destination service registries.
7. Examine the Unpublish APIs report window and check for any errors that occurred
during the unpublishing process.
The Unpublish APIs report window displays the following information:
Name The name of the unpublished API.
Status The status of the unpublishing process.

Success
Failure

unpublishing process fails or if a warning
occurs.
later.
file.
The APIs are unpublished from the selected service registries for the current API
Gateway instance. Once an API is unpublished, the Republish icon changes to Publish
icon.
Modifying API Details

You can modify API details, as required, from the API details page.
M
Odd Header
APIs
To modify API details

3. Click Edit.
Note: If the API is in the active state, you cannot modify the name and version of
the API. The API mocking section is unavailable for any changes.
4. Modify the information as required.

5. Click Save.
Note: If the API is in the active state when you modify API details, the active
API is replaced with the modified API.
The modified APIs do not become effective for ongoing requests.
Updating APIs
You can update the definition of an existing API by uploading WSDL, Swagger, or
RAML file or URL. The uploaded file can also be in a ZIP format. When an API is
updated, it retains the Expose to consumers seings, the existing scope definitions, the
configured policies, and the REST-enabled path configurations for SOAP API. You can
also edit an API using the Edit option for minor edits, whereas the update feature helps
you to overwrite the complete API definition using a file or a URL at the same time.
You can update an active API. You cannot modify the name and version of an API while
updating an active API.
Note: The active APIs are replaced with the updated API. The updated APIs do
not become effective for ongoing requests. Updates to an activated API are
propagated across a cluster and trigger a hot deploy on each cluster node
separately.
You can update an existing API in the following ways:

By importing an API definition from a file
By importing an API definition from a URL
M
Even Header
APIs
Updating an API by Importing an API from a File

You must have the API Gateway's manage APIs or Activate/deactivate APIs functional
privilege assigned to perform this task. You can not update an API by importing an API
from a file if the API is in the active state.

2. Select the required API from the list of APIs.
3. Click Update.
4. Select Update API by importing from file.
Field Description
Select file Click Browse to browse to the location of file to

be imported and select the required file or ZIP
format file.
The REST API can be updated using only the
Swagger or RAML file type. The SOAP API can
be updated using only the WSDL file type.
Root File Name If you have selected a file in ZIP format, type
the relative path of the main file within the ZIP
file.
Name Name for the API. Edit or delete the name of the
existing API displayed.
If you provide an API name, this overwrites
the API name mentioned in the uploaded
file and the API is updated with the name
provided.
If you do not provide an API name, the API
name mentioned in the uploaded file is picked
up and the API is updated with that name.
Type Select the required type. The available types are

RAML, Swagger, and WSDL.
For a REST API, the available options are
RAML and Swagger.
M
Odd Header
APIs
Field Description
For a SOAP API, the available option is WSDL.
Version Version number of the API. The existing version

number of the API is automatically displayed.
You can edit or delete the version number. If
the version number is deleted and the imported
file does not have a version number, then the
system automatically assigns a version number
during the update.
This overwrites the version of the API.
Description Description of the API. The existing description

of the API is automatically displayed. You can
edit or delete the description. If you delete
the description then the description from the
imported file is used.
6. Click Update.
The API definition is updated with the latest changes from the file and is displayed
in the API details page.
Updating an API by Importing an API from a URL


3. Click Update.
4. Select Update API by importing from URL.
Field Description
URL Type the URL from which the API is being

imported.
Note:The REST API can be updated using only

the Swagger or RAML type information that
the URL is pointing to. The SOAP API can
M
Even Header
APIs
Field Description
be updated using only the WSDL file type
information that the URL is pointing to. The
entity sets, singletons, function imports, and
action imports of an OData API can only be
updated by a re-import of the OData API
definition through the URL.
Protected Select this option if you want to import an API

from a URL that is password protected. The
user name and password fields are displayed
using which you can access the provided URL.
Username Type the user name required to access the

password protected URL.
If you have selected the Protected option, this
field is displayed.
Password Type the password associated with the

username.
If you have selected the Protected option, this
field is displayed.
Name Name for the API. The existing name of the API
is automatically displayed.
If you provide an API name, this overwrites
the API name mentioned in the file referred
by URL and the API is updated with the name
provided.
If you do not provide an API name, the API
name mentioned in the file referred to by URL
is picked up and the API is updated with that
name.
Type Select the required type. The available types are

RAML, Swagger, WSDL, and OData.
For a REST API, the available options are RAML
and Swagger.
For a SOAP API, the available option is WSDL.
For a OData API, the available option is OData.
M
Odd Header
APIs
Field Description
Version Version number of the API. The existing version

number of the API is automatically displayed.
You can edit or delete the version number. If the
version number is deleted and the file referred
to by URL does not have a version number,
then the system automatically assigns a version
number during the update.
This overwrites the version of the API.
Description Description of the API. The existing description

of the API is automatically displayed. You can
edit or delete the description. If you delete the
description then the description from the file
referred to by URL is used.
6. Click Update.
The API definition is updated with the latest changes from the URL and is displayed
API Mocking
Using API Gateway, you can mock an API by simulating the native API. For example, if
you have an API without a native implementation, you can mock that API. The mocked
response is returned to the consumer when the API is invoked.
In API Gateway, when you enable mocking for an API, a default mock response is
configured for each combination of resource, operation, status code, and content-type
based on the example and schema specified in that API. You can add a condition to the
operation in the resource.
Note: You cannot enable or disable mocking for an active API.
As an API Provider, you can create or modify the default mock response. You can
specify conditions and associate an IS service with the mocked API. When an IS
service is associated with a mocked API, the associated IS service must adhere to the
apigateway.specifications:mockService specification.
At runtime, when the mocked API is invoked, instead of calling the native API, API
Gateway returns the mocked response to the consumer based on the following priorities:
1. If any of the conditions for the invoked operation satisfies, API Gateway returns the
associated mocked response.
M
Even Header
APIs
2. If any of the conditions for the invoked operation is not satisfied, and if an IS service
is configured for the API, then API Gateway invokes the IS service and returns the IS
service response.
3. If any of the conditions for the invoked operation is not satisfied, and if an IS
service is not configured for the API, then API Gateway returns the default mocked
response.
API mocking is supported only for SOAP and REST APIs.
Note: You must have the API Gateway's manage APIs or activate/deactivate APIs
functional privilege assigned to perform API mocking.
Enabling API Mocking

You can enable or disable API mocking through the API details page.
Note: You cannot enable or disable API mocking for active APIs.
To enable API mocking

2. Select the required API from the list of available APIs.
The API details page for the selected API appears.
3. Click Enable mocking.
This generates the default mock responses.
Modifying API Mocking Details

You must select Enable mocking from the API details page.
You can modify API mocking details, as required, from the API details page.
To modify API mocking details

3. Click Edit.
4. Click API mocking.
5. Specify the following information in the IS service section:
M
Odd Header
APIs
Field Description
Invoke service Specifies the webMethods Integration Server

service to be invoked.
Run as user Type the user name you want API Gateway to
use to invoke the IS service.
6. Select the operation that you want to modify from the Mocked responses section.
7. Click Add Response if you want to add a response and select the status code from the
drop-down.
8. Click .
This adds the status code created to the existing status code list.
9. Select the status code you want to modify.
10. Click + Add Response Header and provide the following information to add the
required response headers:
Field Description
Header key Specify the HTTP header key that would be

contained in the header of HTTP response.
Header value Specify the HTTP header value that would be

contained in the header of HTTP response.
You can add more response headers by clicking .
11. Click + Add Content-type to add a content-type to the status code selected and provide
the following information:
Field Description
Content type Select the content-type to be added to the

selected status code from the drop-down list.
Mock payloads Specify a mock response payload for the

content-type selected.
You can add more content-types by clicking .
M
Even Header
APIs
12. Click + Add Conditions to add a condition to the operation in the resource:
Field Description
Condition name Specify the name for the condition.
Condition parameter Select the type to which the condition is to be

applied. The available options are:
Body
Header
Query parameter (Applicable only for REST
APIs)
Key The key can be a string for the header and query
parameter and for body it can be a JSON path or
an XML path.
Value The value of the condition. Additionally, you

can type an * (asterisk) to ignore the value
specified in this parameter and the condition is
satisfied based on the value specified in the Key
parameter.
Status code Select the status code from the drop-down list.
Note: You must enable the property Send native

provider fault in the Administration > General
> API fault section in order to have correct
mock response for status code 506.
While invoking an API remember
to use the query parameter
expectedStatusCode in order to have
correct mock responses for status codes
100 and 202.
+ Add Response Header Add a response header to the resource selected

by providing the following information:
Header key. Specify the HTTP header key that
would be contained in the header of HTTP
response
M
Odd Header
APIs
Field Description
Header value. Specify the HTTP header value

that would be contained in the header of HTTP
response.
+ Add Content-type Add a content-type to the status code selected by

providing the following information:
Content type. Select the content-type to be added
to the selected status code from the drop-down
list.
Mock payload. Specify a mock response payload
for the content-type selected.
You can add more conditions by clicking .
13. Click Save.
Custom Replacer
API Gateway allows you to send a dynamic custom response instead of a static
mocked response to the consumer when the mocked API is invoked. In the mocked
response, you can specify multiple custom replacers. Custom replacer is used
to replace the custom variables with the values defined in the request headers,
query parameters, and request body. The custom replacer is available in the
${request.<ConditionParameter>.<Key|JsonPath|XPath>} format. The custom
replacers are:
${request.header.<headerKey>}: To replace the value of the headerKey from the
request headers.
${request.query.<queryKey>}: To replace the value of the queryKey from the
query parameters in the request URL.
${request.body.<JsonPath|XPath>}: To replace the value of the <JsonPath|
XPath> from the request body.
Attaching Documents to an API

Pre-requisites:
You must have the Manage APIs functional privilege assigned to perform this task.
You can associate an input document that includes the RAML, Swagger, or WSDL
specification, and additional documents such as programming guides, sample code,
M
Even Header
APIs
script files, and project plan with an API. For example, SOAP APIs can contain external
documents such as Functional Requirements, Error Messages, Release Notes, and so on.
When aaching a document to an API, keep the following points in mind:
You cannot aach or modify a document to the API if it is in active state. You have to
deactivate the API before aaching or modifying it.
API Gateway relies on file extensions to determine a file's type. When you upload
a file from your local machine to the API, be sure the name of the file on your local
machine includes a file extension so that API Gateway can determine the file's type
and aach it correctly to the API.
You cannot upload types of files that are restricted for aaching as the input
document to the API.
API Gateway provides the ability to restrict certain kinds of files from
being uploaded to the API, based on the file extension. The list of
restricted files may vary depending on the file extensions configured in the
apiDocumentsRestrictedExtension property under Administration > Extended
settings section.
When you try to upload a file type that is restricted, API Gateway prompts you with
an error message.
By default, several standard file extensions are blocked in API Gateway, including
any file extensions that are treated as executable files by Windows Explorer. The file
extensions blocked by default are - .bat, .bin, .dll, and .exe.
You cannot upload files that exceed the maximum allowed size for the API.
API Gateway provides the ability to limit the maximum file upload
size to the API. The maximum file upload size is configured in the
apiDocumentsUploadSizeLimitInMB property under Administration > Extended
settings section.
When you try to upload a file that exceeds the maximum file upload size, API
Gateway prompts you with an error message.
You can rename an uploaded document. When you rename a document, only the
display name of the document could be modified, not the document itself. If you
want to modify the document as well, you must delete the file aachment, and aach
the latest file.
To attach document
2. Select the required API.
3. Click Edit.
M
Odd Header
APIs
4. Click Documentation.
5. Click Browse to select a file and upload it.
6. Rename the document in the Display Name field as required.
This is the display name of the document in the API details page.
7. Click Add.
The aached document is listed in a table. You can edit and delete the document by
clicking the and icons.
8. Repeat steps 5 to 7 for each document that you want to aach to the API.
9. Click Save.
SOAP to REST Transformation

SOAP APIs are commonly used to expose data within enterprises. With the rapid
adoption of the REST APIs, API providers must be able to provide RESTful interfaces
to their existing SOAP APIs instead of creating new REST APIs. Using the API Gateway
SOAP to REST transformation feature, the API provider can either expose the parts of
the SOAP API or expose the complete SOAP API with RESTful interface. API Gateway
allows you to customize the way the SOAP operations are exposed as REST resources.
Additionally, the Swagger or RAML definitions can be generated for these REST
interfaces.
Note: You must have the API Gateway's manage APIs or activate/deactivate APIs
functional privilege assigned to perform this task.
Activating SOAP to Rest Transformation

You must have the API Gateway's manage APIs functional privilege assigned to perform
this task.
To activate SOAP to REST transformation for a SOAP operation

3. Click Edit.
4. Click REST transformation.
A list of SOAP operations already exposed to the consumers as well as to be
transformed from SOAP to REST appears. By default, all the SOAP operations are in
inactive state.
M
Even Header
APIs
5. Click to activate the SOAP to REST transformation for the SOAP operations.
Alternatively, you can activate the SOAP to REST transformation for multiple SOAP
operations simultaneously by clicking the Transform all operations activation toggle
buon.
6. Select the operation to edit the SOAP operations.
7. Click Save.
A list of REST resources for the SOAP operations appears. Click on each resource to
view the details that are already available as REST definitions.
Modifying the REST Definitions for SOAP Operations

this task.
To modify the REST definitions for SOAP operation

3. Click Edit.
transformed from SOAP to REST appears.
5. Click to provide the Resource name and Resource path.
buon.
Field Description
Resource name Name of the resource.

The existing name of the SOAP operation
automatically appears, you can modify this
name.
M
Odd Header
APIs
Field Description
Resource path Path of the resource.

The existing path of the SOAP operation
automatically appears, you can modify this
path.
8. Click + Add Parameter and provide the following information to add the required
resource level parameters:
Field Description

Available values - Path, Query-string

Available values - String, Date, Date time, Integer,
Double, Boolean.
Repeat Applicable to parameters of type query.

The query parameter value can take comma
separated array values.
Value Specifies the possible value.
XPath XPath. Specifies how the request parameter must

be mapped to the SOAP payload that is sent to
the native SOAP service. For example,
/soapenv:Envelope/soapenv:Body/
axis:sayHello/axis:name, or //axis:name
( If the SOAP request has only one element such
as name).
Namespace prefix Specifies the namespace prefix of the element

that appears in the XPath.
M
Even Header
APIs
Field Description
Namespace URI Specifies the namespace URI for the XPath

element.
You can add more namespace prefixes and
namespace URIs by clicking .
You can add more parameters by clicking .
9. Select one of the available methods: GET, POST, PUT, or DELETE. By default, POST
is selected.
By default, API Gateway generates the sample JSON request and response based
on the XML schema definitions of the SOAP API. Additionally, you can provide a
schema and modify the generated sample.
10. Click Add Request and provide the schema and a sample for the content-type.
11. Click Add Response and select the status code from the drop-down and provide a
description for the status code selected.
Additionally, to add a content-type to the status code selected, click the status
code to which you want to add a content-type and select the Content type. Provide
a schema and a sample for the content-type selected. By default, status code 200 is
automatically generated by the system.
transformed from SOAP to REST appears. By default, all the SOAP operations are in
inactive state.
13. Click to activate the SOAP to REST transformation for the SOAP operations.
buon.
15. Click Save.
A list of REST resources for the SOAP operations appears. Click on each resource to
view the details that are already available as REST definitions.
17. Click Save.
M
Odd Header
APIs
Supported Content-types and Accept Headers

The following table specifies the content-type available for the HTTP methods:
HTTP Content-types Accept Headers

Method
GET application/x-www-form- application/json

urlencoded
application/xml or text/xml
multipart/form-data or
multipart/mixed
POST application/json application/json
application/xml or application/xml or text/xml

text/xml
multipart/form-data or multipart/mixed
multipart/mixed
application/x-www-form-
urlencoded
PUT application/json application/json
application/xml or application/xml or text/xml

text/xml
multipart/form-data or multipart/mixed
multipart/mixed
application/x-www-form-
urlencoded
DELETE application/x-www-form- application/json

urlencoded
application/xml or text/xml
multipart/mixed
Note: If a content-type is not specified, then the request verifies the value of the
Set Media Type parameter. If the value of the Set Media Type parameter
is not defined, then by default, for POST and PUT HTTP methods, the
application/json content-type is used. Whereas for GET and DELETE
HTTP methods, the application/x-www-form-urlencoded content-type is
used.
M
Even Header
APIs
REST API Endpoints

After providing the information required for the SOAP to REST transformation and
activating the API, the API can be invoked as either SOAP or REST API.
The REST transformation of the SOAP API does not change the API name. The only
change to the SOAP invocation is that the <resource-path-for-the-operation> is
appended:
/ws/<API-NAME>/<version-number>/<resource-path-for-the-resource>
Note: The REST-enabled SOAP API cannot be invoked using the /rest directive.
Samples for REST Request

application/json
The following table provides the samples of the REST request for the application/
json content-type application and the equivalent SOAP request after transformation
from REST to SOAP:
Request Equivalent SOAP Request

{ <soapenv:Envelope xmlns:soapenv=
Consists of only "name":"user1" "http://schemas.xmlsoap.org/soap/envelope/
one element } " xmlns:axis="http://ws.apache.org/axis2">
<soapenv:Body>
(qualified <axis:sayHello>
namespaces) <axis:name>user1/axis:name>
</axis:sayHello>
</soapenv:Body>
</soapenv:Envelope>
Consists of only "name":"user1" "http://schemas.xmlsoap.org/soap/envelope/
one element } " xmlns:axis="http://ws.apache.org/axis2">
<soapenv:Body>
(non-qualified <axis:sayHello>
namespaces) <name>user1</name>
</axis:sayHello>
</soapenv:Body>
</soapenv:Envelope>
Consists of "a":"1", "http://schemas.xmlsoap.org/soap/envelope/">
multiple "b" : 2 <soapenv:Body>
} <addInts>
elements <a>1</a>2
</addInts>
</soapenv:Body>
</soapenv:Envelope>
M
Odd Header
APIs
application/xml and text/xml

The following table provides the samples of the REST request for the application/
xml and text/xml content-type application and the equivalent SOAP request after
transformation from REST to SOAP:

<soapenv:Envelope xmlns:soapenv=
Consists of only <axis:name "http://schemas.xmlsoap.org/soap/envelope/
one element xmlns:axis="http://" xmlns:axis="http://ws.apache.org/axis2">
<soapenv:Body>
and namespace ws.apache.org/ <axis:sayHello>
added by the axis2">user1</ <axis:name>user1</axis:name>
client axis:name> </axis:sayHello>
</soapenv:Body>
</soapenv:Envelope>
<someOtherNamespace:name
Consists of only xmlns:toMed="http://someOtherNamespace">user1</
"http://schemas.xmlsoap.org/soap/envelope/
one element someOtherNamespace:name>
" xmlns:axis="http://ws.apache.org/axis2">
<soapenv:Body>
and client does <axis:sayHello>
not send the <axis:name>user1</axis:name>
Namespace </axis:sayHello>
</soapenv:Body>
</soapenv:Envelope>
Consists of only <toMed:name "http://schemas.xmlsoap.org/soap/envelope/"
one element xmlns:axis="http://ws.apache.org/axis2">
xmlns:toMed="http://
<soapenv:Body>
and the client tOMed">user1</ <axis:sayHello>
sends a different toMed:name> <axis:name>user1</axis:name>
namespace to </axis:sayHello>
API Gateway </soapenv:Body>
</soapenv:Envelope>
<addInts> <soapenv:Envelope xmlns:soapenv=
Multiple XML <a>2</a> "http://schemas.xmlsoap.org/soap/envelope/">
elements 3 <soapenv:Body>
</addInts> <addInts>
<a>2</a>3
</addInts>
</soapenv:Body>
</soapenv:Envelope>
Path and Query Parameters

The following table provides the samples of the REST request having path and query
parameters and the equivalent SOAP request after transformation from REST to SOAP:

<ws:addInts xmlns:ws="http:test">
Simple query or /ws/ <num1>10</num1></ws:addInts>s
path parameter CalcService/
add/{num1}
M
Even Header
APIs
or
/ws/
CalcService/
add?num1=10
Multiple /ws/ <ws:addInts

query or path CalcService/ xmlns:ws="http:test">
parameters add/{num1}/ <num1></num1> <num2></
{num2} num2></ws:addInts>
or
/ws/
CalcService/
add?
num1=10&num2=3
or
/ws/
CalcService/
add/
{num1}&num2=3
<ws:addInts
Hierarchical /ws/ xmlns:ws="http:test">
elements CalcService/ <num1></num1> <num2></
num2></ws:addInts>
add/{num1}/
anotherNumber/
{num2}
multipart/form-data
If you send the multipart/form-data content-type as the REST request, then you need
to optimize the method to be used. This optimization is based on the value specified in
the SOAP Optimization Method parameter available in Routing policy. The default
optimization type is Message Transmission Optimization Mechanism (MTOM). For
example, API Gateway converts REST requests with multipart/form-data and
multipart/mixed types as follows:
1. The Multipurpose Internet Mail Extensions (MIME) parts that have a content ID or
name that match the elements of type base64Binary or hexBinary in the schema
are added as aachments to the outbound request.
2. Parts other than the content ID or name types are converted into XML depending on
the content-type of the MIME part. The application/xml and application/json
content-types are converted. If API Gateway is unable to process the MIME part, it
wraps the MIME part inside an XML element with the name of the content ID.
M
Odd Header
APIs
Limitations
The following limitations apply when you perform a SOAP to REST transformation:
When the API provider defines the mapping for the SOAP operation to the REST
resource or method, API Gateway allows him to specify either the path and the
query parameters or the body but not both. These mappings are used when
transforming the incoming REST request to the SOAP request.
If both path and query parameters and body are sent in the incoming REST request,
then the path and the query parameters are ignored.
If your REST resource accepts the text/xml content-type, then you cannot modify
the default resource path and resource name automatically generated by the system.
This name must be same as the SOAP operation name. However, this limitation is
not applicable for other content-types.
The HTTP method filters of the global policy are not applicable to the REST
transformed method of the SOAP API.
The REST (REST transformed SOAP operations) resources do not appear as general
REST resources when filtered in the Scopes section of the API in API Gateway.
You cannot apply the Inbound Authentication-Message policy to the SOAP operation
enabled as REST.
The SOAP services that have Web Services Interoperability Organization (WS-I) non-
compliant WSDLs cannot be REST-enabled.
Versioning APIs
API Gateway supports the creation of new API versions from the existing versions. The
new API has the same metadata but with an updated version. The version can either be
a number or a string.
The API details page has a drop-down list that displays all the existing API versions.
You can create a new version of an API and retain applications that are associated with
older versions of the API. When an API is updated, it retains the Expose to consumers
seings, the existing scope definitions, the configured policies, and the REST-enabled
path configurations for SOAP API.
Creating New API Version

this task.
You can create a new version of an API from the latest version available for the API. For
example, if the existing version is 1.1 for an API, you can create a version 1.2. If you want
to create a version 1.3, you can only create it from the latest version 1.2 and not from
M
Even Header
APIs
1.1. However, you can delete the intermediate versions. Additionally, even though the
owner of the older API version is a different provider, when you create a new version of
the API, you are the owner of the newly created version of the API. The new API version
is in inactive state, irrespective of the state of the API from which it was versioned.
To create a new version

3. Click Create new version.
4. In the Version field, type the new version for the API.
5. Clear the Retain applications checkbox if you do not want to retain applications that
are associated with older versions of the API.
6. Click Create.
The Version drop-down lists the newly created API version in latest to older order in the
API details page. The corresponding API details page is displayed when you select any
particular version.
Note: The version is appended to the Gateway endpoint(s) URL once the API is
activated and this can be seen in the Technical information section of the API
details page. When a client application invokes the API without the version in
the endpoint, API Gateway invokes the latest version.
API Scopes
API definitions can be complex and span across multiple REST resources and methods,
or SOAP operations for an API. To reduce the complexity of an API definition, you can
define scopes and impose a set of policies on each scope to suit your requirements.
A scope represents a logical grouping of REST resources, methods, or both, and SOAP
operations in an API. You can then enforce a specific set of policies on each individual
scope in the API.
An API can have a set of declared scopes. The available scopes for an API are listed in
the Scopes tab of the API details page.
Creating an API Scope

Scopes enable you to group a set of REST resources, methods, or both, and SOAP
operations for an API.
A scope consists of a name, description, and zero or more resources, methods, or
operations. An API can have zero or more scopes.
M
Odd Header
APIs
You can define a set of policies and configure its properties for each individual scope.
These policies apply to each of the resources, methods, or operations that are associated
to the scope.
Instructions throughout the remainder of this guide use the term scope-level policy when
referring to a set of policies configured for an individual scope of the API.
Note: Ensure that you have a unique set of resources, methods, or operations in
every scope in the API.
To create a scope
A list of APIs available in API Gateway appears.
2. Click the name of the required API.
This opens the API details page.
3. Click Edit.
If the API is active, API Gateway prompts you to deactivate it.
4. Click the Scopes tab.
This displays a list of scopes available in the API.
5. In the List of scopes section, click Add scope.
6. In the Basic information section, provide the required information for each data
fields that appears:
Field Description
Name Name of the scope. A scope name must be

unique within an API.
Note:API Gateway automatically adds the name

New Scope to the Name field. You can
change the name of the scope to suit your
needs. But you cannot leave this field empty.
Description Description of the scope.
7. Applicable only for REST APIs. In the Resources and methods section, select the
resources, methods, or both, you want to associate to this scope.
When selecting a resource or method for the scope definition, you can select whether
you want some or all of the methods within that resource to be selected as well.
8. Applicable only for SOAP APIs. In the Operations section, select the operations you
want to associate to this scope.
M
Even Header
APIs
9. Click Save.
The scope is created and listed in the List of scopes section.
Post-requisites:
Activate the API when you are ready to put it into effect.
To apply and configure policies for this API scope, see “ Creating a Scope-level
Policy” on page 373.
Viewing List of API Scopes and Scope Details

The Scopes tab in the API details page displays a list of all available scopes in the API.
In addition to viewing the list of scopes, you can also examine and modify the details of
a scope, and delete a scope in the Scopes tab.
To view the scope list and properties of a scope

4. In the List of scopes section, click the name of the scope you want to examine.
This opens the details of the scope. The scope details appear in the following
sections:
Basic information: This section contains a summary of basic information such as
name and description of the scope.
Resources and methods: Applicable only for REST APIs. This section contains a
collection of REST resources, methods, or both, that are associated to the scope.
Operations: Applicable only for SOAP APIs. This section contains a collection of
SOAP operations that are associated to the scope.
Modifying API Scope Details

You use the Scopes tab in the API details page to examine and modify the details of a
scope.
To modify the properties of a scope

M
Odd Header
APIs

3. Click Edit.
If the API is active, API Gateway displays a warning message to let you know that
the API is active.
5. In the List of scopes section, click the name of the scope you want to modify.
This opens the details of the scope. The scope details appears in the following
sections:
Basic information: This section contains a summary of basic information such as
name and description of the scope.
Resources and methods: Applicable only for REST APIs. This section contains a
collection of REST resources, methods, or both, that are associated to the scope.
Operations: Applicable only for SOAP APIs. This section contains a collection of
SOAP operations that are associated to the scope.
6. Modify the basic properties, applicable resources, methods, or operations of the
scope.
7. Click Save.
Activate the API, if it is not active, to put it into effect.
Deleting an API Scope

You delete a scope to remove it from the API permanently.
When a scope is deleted from the API definition, API Gateway deletes the existing
associations between the scope and the collection of resources, methods, or operations in
the API. But, the collection of resources, methods, or operations continue to exist in the
API.
To delete a scope
3. Click Edit.
M
Even Header
APIs
the API is active.
This tab displays a list of scopes available with the API.
5. In the List of scopes section, locate the name of the scope you want to delete.
6. Click the Delete ( ) icon next to the scope name.
The scope is removed from the List of scopes section.
8. Click Save to save the updated API.
Example: Usage Scenarios of API Scopes

API Provider can restrict the enforcement of policies at the resource-level or method-
level for a REST API, and at the operations-level for a SOAP API. This policy
enforcement on the resources, methods, or operations of the API will apply in
addition to the default enforcement of policies at the global-level and the user-defined
enforcement of policies at the API-level.
Consider you have a REST API, for example, PhoneStore API, with a collection of
resources and methods.
Resource Name Resource Path Supported

Methods
Resource A /phones/orders GET
POST
Resource B /phones/orders/{order-id} GET
PUT
DELETE
Resource C /phones/orders/{order-id}/ GET

paymentdetails
POST
M
Odd Header
APIs
In the following section, we demonstrate the application of scopes and the policy
enforcement using Resource C: /phones/orders/{order-id}/paymentdetails of the
PhoneStore API.
You can create scopes in the PhoneStore API, and define the individual scopes with a
specific set of resources, methods, or both.
Scope Name Applied Resource Applied

Method
PAYMENT Scope Resource C: /phones/orders/{order-

id}/paymentdetails
WRITE Scope Resource C: /phones/orders/{order- POST

id}/paymentdetails
Assume you have an API-level policy which enforces an Identify and Authorize
Application policy with HTTP Basic Authentication for the PhoneStore API. Now, you
might need to have different authentication mechanisms for different methods and
resources (collectively, scopes) of the PhoneStore API, depending on the level of access
you need.
For example, you might want to enforce an Inbound Authentication - Transport policy
with Require HTTP Basic Authentication for the Resource C in PAYMENT Scope
to enforce secured access to the data. You might also want to apply an Identify and
Authorize Application policy with API Key authentication and Throling Traffic
Optimization policy (with 5 API invocations per minute), in particular, for the POST
method of the Resource C in WRITE Scope to enforce a higher-level of secured access
and manipulation of the REST data.
API-level / Scope-level Policy Applied Policies
API-level Policy Identify and Authorize Application policy

with HTTP Basic Authentication
Scope-level Policy for Inbound Authentication - Transport

PAYMENT Scope
Scope-level Policy for WRITE Identify and Authorize Application policy

Scope with API Key
Throling Traffic Optimization
The API Scopes definition looks like this:
M
Even Header
APIs
API-level Policy Identify and Authorize Application policy with HTTP Basic
Authentication
Policy for Resource C: /phones/ Inbound

PAYMENT orders/{order-id}/ Authentication -
Scope paymentdetails Transport
Policy for Resource C: /phones/ POST Identify and

WRITE Scope orders/{order-id}/ Authorize
paymentdetails Application policy
with API Key
Throling Traffic
Optimization
The precedence of the policy enforcement effective for an API at run-time is as follows:
1. Global Policy Enforcement
2. Method-level Policy Enforcement (REST APIs) -OR- Operation-level Policy
Enforcement (SOAP APIs)
3. Resource-level Policy Enforcement (REST APIs)
4. API-level Policy Enforcement
The specific aspect of processing during the handling of an API invocation at run-time in
API Gateway can be best understood with the following scenarios:
Scenario A: Invoke GET method on the Resource C: /phones/orders/{order-id}/
paymentdetails
Global Policy: Not applicable
Method-level Policy: Not applicable
Resource-level Policy(s): Inbound Authentication - Transport
API-level Policy: Identify and Authorize Application policy with HTTP Basic
Authentication
As per the precedence of policy enforcement, the Inbound Authentication - Transport at
the resource-level and the Identify and Authorize Application policy with HTTP Basic
Authentication at the API-level are enforced at run-time.
The effective policy set enforced on the API for the GET method at run-time includes:
Inbound Authentication - Transport
Identify and Authorize Application policy with HTTP Basic Authentication
Scenario B: Invoke POST method on the Resource C: /phones/orders/{order-id}/
paymentdetails in WRITE Scope
M
Odd Header
APIs

Method-level Policy(s): (1) Identify and Authorize Application policy with API Key
(2) Throling Traffic Optimization
Authentication
As per the precedence of policy enforcement, the Identify and Authorize Application
policy with API Key at the method-level takes precedence over the Identify and
Authorize Application policy with HTTP Basic Authentication at the API-level, and is
enforced at run-time.
The effective policy set enforced on the API for the POST method at run-time includes:
Identify and Authorize Application policy with API Key
Now, consider that you apply an active Global Policy that has the Identify and
Authorize Application policy with Hostname Address for all REST APIs (including our
PhoneStore API).
Scenario C: Invoke POST method on the Resource C: /phones/orders/{order-id}/
paymentdetails in WRITE Scope
Global Policy: Identify and Authorize Application policy with Hostname Address
(2) Throling Traffic Optimization
Authentication
policy with Hostname Address applied through the global policy takes precedence over
every other Identify and Authorize Application policy that is applied at the method-level
and the API-level, and is enforced at run-time.
The effective policy set enforced on the API for the POST method at run-time includes:
Identify and Authorize Application policy with Hostname Address
Resolving Scope Conflicts
When you save an API, API Gateway combines the scopes specified with the set of
policies defined at the API-level, and on saving the API, API Gateway applies the
policies to the API at various enforcement levels. API Gateway validates the scope list to
M
Even Header
APIs
ensure that it contains no conflicting or incompatible policies. If the list contains conflicts
or inconsistencies, API Gateway prompts you with an error message.
Consider that you modify the existing UPDATE scope to include a POST method for
Resource C. The API Scopes definition now looks like this:
API- Identify and Authorize Application policy with HTTP Basic

level Authentication
Policy
Policy Resource C: /phones/ Inbound

for orders/{order-id}/ Authentication -
PAYMENT paymentdetails Transport
Scope
Policy Resource C: /phones/ POST Identify and

for orders/{order-id}/ Authorize
WRITE paymentdetails Application policy
Scope with API Key
Throling Traffic
Optimization
Policy Resource C: /phones/ POST Identify and

for orders/{order-id}/ Authorize
UPDATE paymentdetails Application policy
Scope with IP Address
Range
Scenario D: Save the updated PhoneStore API.

(2) Identify and Authorize Application policy with IP Address Range (3) Throling
Traffic Optimization
Authentication
policy at the method-level in WRITE and UPDATE Scopes take precedence over
the Identify and Authorize Application policy at the API-level. But the Identify and
Authorize Application policy with the API Key and IP Address Range authentications
that are applied at the method-level results in a policy conflict.
To resolve the conflicts, you can choose one of the following workaround:
M
Odd Header
APIs
Option 1: Remove the existing association between the POST method and the WRITE
Scope or UPDATE Scope through the API Scope details.
Option 2: Delete the WRITE Scope or UPDATE Scope.
Option 3: Remove the Identify and Authorize Application policy from the WRITE
Scope or UPDATE Scope.
Exposing a REST API to Applications

The API Provider can restrict the exposure of specific resources and methods of a REST
API to other applications.
Consider you have a native REST API created in API Gateway with resources - Resource
A, Resource B, and Resource C. You might want to expose Resource A and Resource C,
and restrict the visibility of Resource B to other applications. You can use the Expose to
consumers buon to switch on the visibility of Resource A and Resource C and switch off
the visibility of Resource B as required. Similarly, you can restrict the visibility of one or
more methods within each individual resource.
If an application aempts to invoke the Resource C in the above REST API, API Gateway
returns a HTTP response code 404.
By default, the Expose to consumers buon is switched on for all resources and methods
of the REST API. Once the API is activated, all of its resources and methods are exposed
to registered applications. If you do not want a particular set of resources and methods,
or a set of methods in a particular resource to be hidden for registered applications,
switch off the Expose to consumers buon in the REST API definition.
Note: Be aware that API Gateway does not allow you to activate a REST API if none
of the methods in the API are selected for exposing to other applications.
You must select at least one method of the REST API to enforce runtime
invocations.
To expose a set of resources and methods of the REST API

3. Click Edit.
the API is active.
4. Click Resources and methods.
This displays a list of resources and methods available in the API.
M
Even Header
APIs
a. To select a resource, switch on the Expose to consumers buon next to the resource
URI.
You can select one or more resources to expose to other applications.
b. To select a method within the resource, click on the resource path. In the
expanded list of methods, switch on the Expose to consumers buon next to the
method name.
You can select one or more methods to expose to other applications.
Exposing a SOAP API to Applications

The API Provider can restrict the exposure of specific operations of a SOAP API to other
applications.
Consider you have a native SOAP API created in API Gateway with operations -
Operation A, Operation B, and Operation C. You might want to expose the Operation
A and Operation C, and restrict the visibility of Operation B to other applications. You
can use the Expose to consumers buon to switch on the visibility of Operation A and
Operation C and switch off the visibility of Operation B as required.
If an application aempts to invoke the Operation C in the above SOAP API, API
Gateway returns a HTTP response code 404.
By default, the Expose to consumers buon is switched on for all operations of the
SOAP API. Once the API is activated, all of its operations are exposed to registered
applications. If you do not want a particular set of operations to be hidden for registered
applications, switch off the Expose to consumers buon in the SOAP API definition.
Note: Be aware that API Gateway will not allow you to activate a SOAP API if none
of the operations in the API are selected for exposing to other applications.
You must select at least one operation of the SOAP API to enforce runtime
invocations.
To expose a set of operations of the SOAP API

This displays a list of APIs available in API Gateway.
3. Click Edit.
the API is active.
M
Odd Header
APIs
4. Click Operations.
This displays a list of operations available in the API.
a. To select an operation, switch on the Expose to consumers buon next to the
operation URI.
You can select one or more operations to expose to other applications.
API Grouping
You can group APIs based on various categories. Categories help consumers locate APIs
easily. For example, if you are offering APIs to help your consumers manage their sales
and ordering beer, classifying the APIs under Sales and Ordering helps them locate
these APIs easily.
The default groups available under which you can group the APIs are Finance Banking
and Insurance, Sales and Ordering, Search, and Transportation and Warehousing. If you want to
include more groups you can update the property apiGroupingPossibleValues under
Administration > Extended settings that enables API grouping. You can modify the existing
list of groups by deleting or adding new group names as comma separated values in this
field. Ensure that the group name does not contain a comma as part of the name.
API grouping can be applied in one of these ways:
While creating an API from scratch
While editing an API
You can select one or more groups in the API grouping field. When an API is published to
API Portal, the published APIs in API Portal are grouped as per the group assigned.
API Tagging
Tags are words or phrases that act as keywords for categorizing, identifying, and
organizing APIs.
In API Gateway, you can assign tags to APIs, and their resources, methods, or
operations. Tags help to logically catagorize APIs in different ways, for example, by
usage, owner, consuming application, or other criteria. Tags are especially useful when
there are multiple APIs of the same type - it enables to quickly identify a specific API
based on the tag assigned to it. For example, you can assign the tag GET-Methods to
specific GET methods in different REST APIs, and use it to search for the list of REST
APIs with the GET-Methods tag in API Gateway.
You can use tagging, for example, to do the following:
M
Even Header
APIs
Tag and untag REST APIs in API Gateway.

Use tags to search for multiple resources and methods across the REST APIs that are
available in API Gateway.
Use tags to search for multiple operations across the SOAP APIs that are available in
API Gateway.
You can assign one or more tags, remove a tag, and view the tags on the API details
page. When a tagged API is published to API Portal, the published API in API Portal is
tagged with the same tag defined in API Gateway.
Adding Tags to an API

Pre-requisites:
Tags are not automatically assigned to APIs, resources, methods, or operations. You
can add one or more tags, and you can remove tags from an API, resource, method, or
operation at any time.
You can define a set of consistent tags that meets your needs for each API, resource,
method, or operation. Using a consistent set of tags makes it easier to manage the APIs,
resources, methods, or operations. You can search the APIs, resources, methods, or
operations based on the tags you add.
When tagging an API, keep the following points in mind:
You cannot tag an API if it is in active state. You have to deactivate the API before
tagging it.
You can assign tags to the following APIs and its components:
SOAP API. You can assign tags to the SOAP API itself and to its operations.
REST API. You can assign tags to the REST API itself and to its resources, and
methods.
REST-enabled SOAP API. You can assign tags to the REST-enabled SOAP API. Also,
you can assign tags to the REST resources and methods which correspond to the
transformed SOAP operations.
OData API. You can assign tags to the OData API only.
You can assign tags to an API, resource, method, or operation only.
When you delete an API, resource, method, or operation in API Gateway, any tags
that were assigned to that API, resource, method, or operation are not deleted.
To tag an API
M
Odd Header
APIs

3. Click Edit.
4. Click Tags.
5. To add tags to the API, resource, method, or operation, do the following:
Tagging an API. In the Basic information section, select an existing tag or type the
new tag in the Search and add tags drop-down list, and then click .
Tagging a Resource or Method. In the Resources and methods section, locate the
required resource or method for tagging, select an existing tag or type the new
tag in the Search and add tags drop-down list, and then click .
Tagging an Operation. In the Operations section, locate the required operation for
tagging, select an existing tag or type the new tag in the Search and add tags drop-
down list, and then click .
The tag is listed next to Added tags. To delete a tag, click the x icon.
6. Click Save.
Exporting APIs
You must have the API Gateway's export assets privilege assigned to perform this task.
Note: API Gateway supports backward compatibility for all the exported APIs from
API Gateway 10.1 version or higher.
To export an API
3. Click to export a single API.
Alternatively, you can select multiple APIs to be exported simultaneously by clicking
the checkboxes adjacent to the names of the API.
Click and select Export from the drop-down list.

The Export archive window appears.
4. Select Include applications if you want to export the applications associated with the
APIs.
5. Click Export.
The browser prompts you to either open or save the export archive.
6. Select the appropriate option and click OK.
M
Even Header
APIs
Exporting Specifications
For a REST API, you can export specifications in Swagger and RAML formats to your
local system. Similarly, for a SOAP API, you can export a specification in WSDL format
to your local system. The exported WSDL is in a ZIP format consisting of the WSDL file
whereas for Swagger and RAML the respective files are directly exported. API Gateway
supports the following versions:
Swagger 2.0 for a Swagger file
RAML 0.8 for a RAML file
You can export APIs that have been created from scratch or by importing their respective
definitions. The Swagger or RAML definition provides the consumer view on a REST
API deployed to the API Gateway. Similarly, the WSDL definition provides the
consumer view on a SOAP API. Consumer view indicates that the Swagger, RAML,
or WSDL definitions contain the API Gateway endpoint and information about those
resources and operations, which are exposed to customers.
Note: In the downloaded Swagger document, the valid JSON schemas aached to a
response or a request does not always appear. Only the valid JSON schemas
appear correctly. For any other schema information just the generic JSON
schema such as {"type":"object"} appears.
To export the specification

2. Select the required API from the list of available APIs .
3. Click Specifications.
4. Based on the type of specification that you have selected to export, select any of the
following:
Swagger data link to export the Swagger specification.
RAML data link to export the RAML specification.
Artifacts link to export the WSDL specification.
OData meta document link to a zip containing the OData API and metadata
document. If the OData API is active, a link to the service document and a link to
the metadata document are also displayed.
When downloading a zip file the browser prompts you to either open or save the zip
file.
M
Odd Header
APIs
Deleting APIs
Deleting an API permanently removes the API from API Gateway.
When deleting an API, keep the following points in mind:
You cannot delete an API if it is in active state. You have to deactivate the API before
deleting it.
You must have the Manage APIs functional privilege.
When you delete an API, performance metrics and event information of the API are
also deleted.
Deleting a Single API

Pre-requisites:
You delete an API to remove it from API Gateway permanently.
To delete an API
2. Click the Delete icon for the API that you want to delete.
3. Select the Force delete option to delete an API forcefully. API Gateway ignores any
failures even if the API is used by other applications, and clears all data from the API
Gateway database.
The API is deleted forcefully.
Deleting Multiple APIs in a Single Operation

Pre-requisites:
You can bulk delete APIs in API Gateway.
To delete multiple APIs in a single operation

2. Select the APIs that you want to delete.
M
Even Header
APIs
3. In the Menu icon, click Delete.

4. Select the Force delete option to delete APIs forcefully. API Gateway ignores any
failures even if the selected APIs are used by other applications, and clears all data
from the API Gateway database.
The APIs are deleted forcefully from API Gateway.
6. Examine the Delete APIs report window and check for any errors that occurred during
the deletion process.
The Delete APIs report window displays the following information:
Name The name of the deleted API.
Status The status of the deletion process. The

Success
Failure
Description A descriptive information if the deletion

fails or if a warning occurs.
later.
file.
Example: Managing an API

This section explains everything you would want to know about an API and how to
manage it with an example API phonestore. You can model an API that serves to expose
API data and functionality as a collection of resources. Each resource is accessible with
unique Uniform Resource Identifiers (URLs). In your API, you expose a set of HTTP
operations (methods) to perform on a specific resource and capture the request and
response messages and status codes that are unique to the HTTP method and linked
within the specific resource of the API.
The basic elements of an API are:
The API itself (for example, phonestore)
Its resource (phones), available on the unique base URL (/phones)
M
Odd Header
APIs
The defined HTTP method (GET) for accessing the resource (phones)
Parameters for request representations (412456)
A request generated for this method (Request 123)
A response with the status code received for this request (Response ABCD)
The example API phonestore that we consider here is defined to support an online
phone store application. Assume, this sample phonestore API currently has a database
that defines the various brands of phones, features in the individual phones, and the
inventory of each phone. This API is used as a sample to illustrate how to model URL
paerns for resources, resource methods, HTTP headers and response codes, content
types, and parameters for request representations to resources.
Base URL
The base URL of an API is constructed by the domain, port, and context mappings of the
API. For example, if the server name is www.phonestore.com, port is 8080, and the API
context is api. The full Base URL is:
http://www.phonestore.com:8080/api
API Parameters
Parameters defined at the higher API level are inherited by all Resources and Methods
included in the individual resources.
API Resources
Resources are the basic components of an API. Examples of resources from an online
phonestore API include a phone, an order from a store, and a collection of customers.
After you identify a service to expose as an API, you define the resources for the API.
For example, for the online phonestore API, there are a number of ways to represent the
data in the phone store database as an API. The verbs in the HTTP request maps to the
operations that the database supports, such as select, create, update, delete.
Each resource has to be addressed by a unique URI. Along with the URI you're going
to expose for each resource, you also need to decide what can be done to each resource.
The HTTP methods passed as part of an HTTP request header directs the API on what
needs to be done with the addressed resource.
Resource URLs
An URL identifies the location of a specific resource.
For example, for the online phonestore API, the resources have the following URLs:
URL Description
http:// Specifies the collection of phones contained

www.phonestore.com/api/ in the online store.
phones
M
Even Header
APIs
URL Description
http:// Accesses a phone referenced by the product

www.phonestore.com/api/ code 412456.
phones/412456
http:// Specifies a set of reviews posted for a phone

www.phonestore.com/api/ of code 412456.
phones/412456/reviews
http:// Accesses a specific review referenced by the

www.phonestore.com/api/ unique ID 78 contained in the reviews of the
phones/412456/reviews/78 phone of code 412456.
API Gateway supports the following paerns of resource URL: a collection of resources
or a particular resource.
For example, in the online phonestore API, the paers are as follows:
Collection URL: http://phonestore.com/api/phones
Unique URL: http://phonestore.com/api/phones/412456/features to retrieve a
collection resource describing the key features of phone whose product code is 412456.
Resource Parameters
Parameters defined at the higher Resource level are inherited by all Methods in the
particular resource; it does not affect the API.
Resource Methods
Individual resources can define their capabilities using supported HTTP methods. To
invoke an API, the client would call an HTTP operation on the URL associated with the
API's resource. For example, to retrieve the key feature information for phone whose
product code is 412456, the client would make a service call HTTP GET on the following
URL:
http://www.phonestore.com/phones/412456/features
Supported HTTP Methods

API Gateway supports the standard HTTP methods for modeling APIs: GET, POST,
PUT, DELETE, and PATCH.
The following table describes the semantics of HTTP methods for our sample Phone
Store API:
M
Odd Header
APIs
Resource URI HTTP Description

Method
/phones/orders GET Asks for a representation of all of the

orders.
/phones/orders POST Aempts to create a new order,

returning the location (in the Location
HTTP Header) of the newly created
resource.
/phones/orders/ GET Asks for a representation of a specific

{order-id} Order resource.
/phones/orders/ DELETE Requests the deletion of a specified

{order-id} Order resource.

{order-id}/status Order's current status.

{order-id}/ Order's payment details.
paymentdetails
/phones/orders/ PUT Updates a specific Order's payment

{order-id}/ details
paymentdetails
Method Parameters
Parameters defined at the lower method level apply only to that particular method; it
does not affect either the API or the resource.
API Parameters
Parameters specify additional information to a request. You use parameters as part of the
URL or in the headers or as components of a message body.
Parameter Levels
A parameter can be set at different levels of an API. When you document a REST API in
API Gateway, you define parameters at the API level, Resource level, or Method level to
address the following scenarios:
If you have the parameter applicable to all resources in the API, then you define this
parameter at the API level. This indirectly implies that the parameter is propagated
to all resources and methods under the particular API.
M
Even Header
APIs
If you have the parameter applicable to all methods in the API, then you define
this parameter at the resource level. This indirectly implies that the parameter is
propagated to all methods under the particular resource.
If you have the parameter applicable only to a method in the API, then you define
this parameter at the method level.
API-level Parameters
Seing parameters at the API level enables the automatic assignment of the parameters
to all resources and methods included in the API. Any parameter value you specify at
the higher API level overrides the parameter value you set at the lower resource level or
the lower method level if the parameter names are the same.
For example, if you have a header parameter called API Key that is used for consuming
an API.
x-Gateway-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a
This parameter is specific to the entire API and to the individual components, that is
resources and methods, directly below the API. Such a parameter can be defined as a
parameter at the API level.
At an API level, API Gateway allows you to define the following types of parameters:
Query-String parameter
Header parameter
Resource-level Parameters
Seing parameters at the resource level enables the automatic assignment of the
parameters to all methods within the resource. Any parameter value you specify at the
higher resource level overrides the parameter value you set at the lower method level if
the parameter names are the same. In contrast, the lower resource level parameters do
not affect the higher API level parameters.
Consider the sample phonestore API maintains a database of reviews about different
phones. Here is a request to display information about a particular user review, 78 of the
phone whose product code is 412456.
GET /phones/412456/user_reviews/78
In the example, /user_reviews/78 parameter narrows the focus of a GET request to

review /78 within a particular resource /412456.
This parameter is specific to the particular resource phone whose product code is
412456 and to any individual methods that are directly below the particular resource.
Such a parameter can be defined as a parameter at the resource level.
At a resource level, API Gateway allows you to define the following types of parameters:
Header parameter
Path parameter
M
Odd Header
APIs
Method-level Parameters
If you do not set parameters at the API level or resource level, you can set them at a
method level. Parameters you set at the method level are used for the HTTP method
execution. They are useful to restrict the response data returned for a HTTP request.
Any parameter value you specify at the lower method level is overridden by the value
set at higher API-level parameter or the higher resource-level parameter if the names are
the same. In contrast, the lower method-level parameters do not affect the higher API-
level or resource-level parameters.
For example, the phonestore API described might have a request to display information
contributed by user Allen in 2013 about a phone whose product code is 412456.
GET /phones/412456/user_reviews/78?year=2013&name=Allen
In this example, year=2013 and name=Allen narrow the focus of the GET request to
entries that user Allen added to user review 78 in 2013.
At a method level, API Gateway allows you to define the following types of parameters:
Header parameter
Parameter Types
API Gateway supports three types of parameters in REST API: Query-String, Header,
and Path.
Let's have a look at different parameter types to see how they can be used for
parameterizing the resources.
Query-String Parameters
Query-String parameters are appended to the URI after a ? with name-value pairs. The
name-value pairs sequence is separated by either a semicolon or an ampersand.
For instance, if the URL is http://phonestore.com/api/phones?
itemID=itemIDValue, the query parameter name is itemID and value is the
itemIDValue. Query parameters are often used when filtering or paging through HTTP
GET requests.
Now, consider the online phonestore API. A customer, when trying to fetch a collection of
phones, might wish to add options, such as, android v4.3 OS and 8MP camera. The URI
for this resource would look like:
/phones?features=androidosv4.3&cameraresolution=8MP
Header Parameters
Header parameters are HTTP headers. Headers often contain metadata information for
the client, or server.
x-Gateway-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a
You can create custom headers, as required. As a best practice, Software AG

recommends that you prefix the header name with x-.
M
Even Header
APIs
HTTP/1.1 defines the headers that can appear in a HTTP response in three sections of
RFC 2616: 4.5, 6.2, and 7.1. Examine these codes to determine which are appropriate for
the API.
Path Parameters
Path parameters are defined as part of the resource URI. For example, the URI can
include phones/item, where /item is a path parameter that identifies the item in the
collection of resource /phones. Because path parameters are part of the URI, they are
essential in identifying the request.
Now, consider the online phonestore API. A customer wishes to fetch details about a
phone {phone-id} whose product code is 412456. The URI for this resource would look
like:
/phones/412456
Important: As a best practice, Software AG recommends that you adopt the following
conventions when specifying a path parameter in the resource URI:
Append a path parameter variable within curly {} brackets.
Specify a path parameter variable such that it exactly matches the path
parameter defined at the resource level.
Parameter Data Types

When you add a parameter to the API, you specify the parameter's data type. The data
type determines what kind of information the parameter can hold.
API Gateway supports the following data types for parameters:
Data Type Description
String Specifies a string of text.
Date Specifies a date stamp that represents a specific date.

The date input parameters allow year, month, and day input.
This data type only accepts date values in the format yyyy-mm-dd
Time Specifies a timestamp that represents a specific time.

The time input parameters allow hour and minute.
This data type only accepts date values in the format hh:mm:ss
Date/Time Specifies a timestamp that represents a specific date and/or time.

The date/time input parameters allow year, month, and day
input as well as hour and minute. Hour and minute default to 0.
M
Odd Header
APIs
Data Type Description
This data type only accepts date values in the format yyyy-mm-
dd; and time values in the format hh:mm:ss
Integer Specifies an integer value for the data type.

This is generally used as the default data type for integral values.
Double Specifies the double data type value.

This is a double-precision 64-bit IEEE 754 floating point and is
generally used as the default data type for decimal values.
Boolean Specifies a true or false value.
Supported HTTP Status Codes

An API response returns a HTTP status code that indicates success or failure of the
requested operation.
API Gateway allows you to specify HTTP codes for each method to help clients
understand the response. While responses can contain an error code in XML or other
format, clients can quickly and more easily understand an HTTP response status code.
The HTTP specification defines several status codes that are typically understood by
clients.
API Gateway includes a set of predefined content types that are classified in the
following taxonomy categories:
Category Description
1xx Informational.
2xx Success.
3xx Redirection. Need further action.
4xx Client error. Correct the request data and retry.
5xx Server error.
HTTP/1.1 defines all the legal status codes. Examine these codes to determine which are
appropriate for your API.
Now, consider the online phonestore API. The following table describes the HTTP status
codes that each of the URIs and HTTP methods combinations will respond:
M
Even Header
APIs
Resource URI Supported Supported HTTP Status Codes

HTTP Methods
/phones/orders GET 200 (OK, Success)
/phones/orders POST 201 (Created) if the Order

resource is successfully created,
in addition to a Location header
that contains the link to the newly
created Order resource; 406
(Not Acceptable) if the format of
the incoming data for the new
resource is not valid
/phones/orders/ GET 200 (OK); 404 (Not Found) if

{order-id} Order Resource not found
/phones/orders/ DELETE 200 (OK); 404 (Not Found) if

{order-id} Order Resource not found

{order-id}/status Order Resource not found

{order-id}/ Order Resource not found
paymentdetails
/phones/orders/ PUT 201 (Created); 406 (Not

{order-id}/ Acceptable) if there is a problem
paymentdetails with the format of the incoming
data on the new payment
details; 404 (Not Found) if Order
Resource not found
Sample Requests and Responses

To illustrate the usage of an API, you provide a sample request and response messages.
Consider the sample phonestore API that maintains a database of phones in different
brands. The phonestore API might provide the following examples to illustrate its usage:
Sample 1 - Retrieve a list of phones
Client Request
GET /phones HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
M
Odd Header
APIs
Accept-Encoding: text/xml
Connection: Keep-Alive
Server Response
HTTP/1.1 200 OK
Date: Mon, 29 August 11:53:27 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Mon, 18 July 2016 09:18:16 GMT
Content-Length: 356
Content-Type: text/xml
<phones>
<phone>
<name>Asha</name>
<brand>Nokia</brand>
<price currency="irs">11499</price>
<features>
<camera>
<back>3</back>
</camera>
<memory>
<storage scale="gb">8</storage>
<ram scale="gb">1</ram>
</memory>
<network>
<gsm>850/900/1800/1900 MHz</gsm>
</network>
</features>
</phone>
<phone>
<name>Nexus7</name>
<brand>Google</brand>
<features>
<camera>
<front>1.3</front>
<back>5</back>
</camera>
<memory>
</memory>
<network>
<gsm>850/900/1800/1900 MHz</gsm>
<HSPA>850/900/1900 MHz</HSPA>
</network>
</features>
</phone>
</phones>
Client Request
GET /phones/phone-4156 HTTP/1.1
Server Response
POST /phones/phone HTTP/1.1
M
Even Header
APIs
Content-Length: 156
<phones>
<phone>
<name>iPhone5</name>
<brand>Apple</brand>
<features>
<camera>
<front>1.2</front>
<back>8</back>
</camera>
<memory>
</memory>
<network>
<gsm>850/900/1800/1900 MHz</gsm>
<HSPA>850/900/1900 MHz</HSPA>
</network>
</features>
<phone>
</phones>
Sample 3 - Create a phone

POST /phones/phone HTTP/1.1
Content-Length: 156
<phones>
<phone>
<name>iPhone5</name>
<brand>Apple</brand>
<features>
<camera>
<front>1.2</front>
<back>8</back>
</camera>
<memory>
</memory>
<network>
<gsm>850/900/1800/1900 MHz</gsm>
<HSPA>850/900/1900 MHz</HSPA>
</network>
</features>
<phone>
</phones>
Server Response
HTTP/1.1 200 OK
Date: Mon, 29 August 11:53:27 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Wed, 18 June 2014 09:18:16 GMT
Content-Type: text/xml
Content-Length: 15
M
Odd Header
APIs
<id>2122</id>
M
Even Header
M
Odd Header
Policies
5 Policies
■ Overview ..................................................................................................................................... 226
■ Policy Validation and Dependencies .......................................................................................... 228
■ Managing Threat Protection Policies ......................................................................................... 236
■ System-defined Stages and Policies ......................................................................................... 246
■ Managing Global Policies .......................................................................................................... 354
■ Managing API-level Policies ...................................................................................................... 369
■ Managing Scope-level Policies .................................................................................................. 372
■ Managing Policy Templates ....................................................................................................... 376
■ Supported Alias and Policy Combinations ................................................................................. 386
M
Even Header
Policies
Overview
API Gateway provides a policy framework to manage and secure APIs.
A policy can be enforced on an API to perform specific tasks, such as transport, security,
logging, routing of requests to target services, and transformation of data from one
format to another. You can also define a policy to evaluate and process the various API
invocations at run-time. For example, a policy could instruct API Gateway to perform
any of the following tasks and prevent malicious aacks:
Verify that the requests submied to an API come from applications that are
authenticated and authorized using the specified set of identifiers in the HTTP
header to access and use the particular API.
Validate digital signatures in the security header of request and response messages.
Monitor a user-specified set of run-time performance conditions and limit the
number of invocations during a specified time interval for a particular API and for
applications, and send alerts to a specified destination when these performance
conditions are violated.
Log the request and response messages, and the run-time performance
measurements for APIs and applications.
Policies are grouped into stages as per their usage. For example, the policies in a Threat
Protection stage can be enforced for all APIs to protect against malicious aacks that
could cause problems such as, large and recursive payloads, viruses, scanning with
external systems, and SQL injections. The policies in the Identify and Access stage can
be enforced on an API to specify the kind of identifiers that are used to identify the
application and authorize it against all applications registered in API Gateway.
Policy enforcement mode
You can enforce policies in an API in the following ways:
Global Policies: You can apply a global policy to all APIs or the selected set of APIs.
You do this by configuring the filters for the API and the policy configuration in the
Global Policy details page. The global policies apply globally to the selected APIs.
Policy Templates: You can apply one or more policy templates to an API. You do this
by applying the policy templates in the API details page. These policy templates
apply at the API-level, and can be customized to suit the needs of a particular API.
API-specific Policies: You can apply one or more individual policies to an API. You do
this by applying the policies in the API details page. These policies apply at the API-
level, and can be customized to suit the needs of a particular API.
API Scope-specific Policies: You can apply one or more policies at the scope-
level of an API. You do this by defining the API scopes with a collective set of
resources, methods, or operations in the API details page. These policies apply
M
Odd Header
Policies
at the corresponding resource-level, method-level, or operation-level, and can be

customized to suit the needs of an individual API scope.
After you apply the policies both globally (through global policies) and directly (through
API-level policies and scope-level policies) to an API, API Gateway determines the
effective set of policies for that API by taking into account the precedence of policy
enforcement at the API-level, the policy stages, the priority of policies, run-time
constraints, and the status (activated or deactivated) of any applied global policy.
Policy hierarchy
You can enforce policies on an API at the following levels:
Global Policy Enforcement: This enforcement applies globally to all APIs defined in API
Gateway.
API-level (API-specific) Policy Enforcement: This enforcement applies to all resources and
its nested methods of a REST API, or all operations of a SOAP API.
Resource-level (Scope-specific) Policy Enforcement: Applicable only for REST APIs. This
enforcement applies to one or more resources and its nested methods in the REST
API.
Method-level (Scope-specific) Policy Enforcement: Applicable only for REST APIs. This
enforcement applies to one or more methods nested within a resource in the REST
API.
-OR-
Operation-level (Scope-specific) Policy Enforcement: Applicable only for SOAP APIs. This
enforcement applies to one or more operations in the SOAP API.
For example, if an API was given the Identify and Authorize Application policy at the
following policy enforcement levels:
3. Resource-level Policy Enforcement
4. Method-level Policy Enforcement (or) Operation-level Policy Enforcement
The precedence of the policy enforcement which are effective for the API at run-time is
as follows:
2. Method-level Policy Enforcement (or) Operation-level Policy Enforcement
3. Resource-level Policy Enforcement
If the API has the Identify and Authorize Application policy applied through both a
global policy and at the API-level, API Gateway does not show conflict. The Identify and
M
Even Header
Policies
Authorize Application policy applied through the global policy takes precedence and is
processed at run-time.
Similarly for a REST API, Identify and Authorize Application policy is applied through
a scope-level policy (at the resource-level) and also at the API-level, the Identify and
Authorize Application policy applied through the scope-level policy takes precedence
and is processed at run-time.
Transaction logging policy
API Gateway provides a system global policy, Transaction logging, which is shipped with
the product. By default, the policy is in the Inactive state. The transaction logging policy
has standard filters and log invocation policy that log request or response payloads to
a specified destination. You can edit this policy to include additional filters or modify
the policy properties but you cannot delete this policy. You can activate this policy in
the Polices > Global policies page or through the Global Policy details page. Activating the
policy enforces it on all APIs in API Gateway based on the configured filters and logs
transactions across all the APIs. If you have multiple log invocation policies assigned
to an API, the policies are compiled into a single policy and the one transaction log is
created per destination.
Policy Validation and Dependencies

When you enforce a policy to govern an API at run-time, API Gateway validates the
policies to ensure that:
Any policy (for example, Log Invocation) that can appear in an API multiple times is
allowed to appear multiple times.
For policies (for example, Require HTTP / HTTPS) that can appear only once in an
API, API Gateway issues an error message.
For policies (for example, Monitor Service Level Agreement) that are dependent and
use another policy in conjunction (for example, Identify and Authorize Application)
in an API, API Gateway prompts you with a warning message to include the
dependent policy.
When you save an API, API Gateway combines the policies from all of the global and
direct policies that apply to the API (that is, at the API-level) and generates what is
called the effective policy for the API. For example, let's say your REST API is within the
scope of two policies: one policy that performs a logging task and another policy that
performs a security task. When you save the REST API, API Gateway automatically
combines the two policies into one effective policy. The effective policy, which contains
both the logging task and the security task, is the policy that API Gateway actually uses
to publish the REST API.
When API Gateway generates the effective policy, it validates the resulting policy to
ensure that it contains no conflicting or incompatible policies.
If the policy contains conflicts or inconsistencies, API Gateway computes the effective
API policy according to policy resolution rules. For example, an effective API policy can
M
Odd Header
Policies
include only one Identify and Authorize Application policy. If the resulting policy list
contains multiple Identify and Authorize Application policies, API Gateway shows the
conflict by including an including a Conflict ( ) icon next to the name of the conflicting
policies in the effective policy.
The following table shows:
The order in which API Gateway evaluates the policies.
Policy dependencies (that is, whether a policy must be used in conjunction with
another particular policy).
Conflicting or incompatible policies.
Whether a policy can be included multiple times in a single API. If a policy cannot
be included multiple times in a single API, API Gateway selects one (depending on
the precedence of the policy at the enforcement level) for the effective policy and
processes at run-time.
Policy Validation and Dependencies:
Policy Applicable API Dependent Mutually Can include

Type Policy Exclusive multiple times in
Policy an API?
Authorize REST Identify None. No. API

User and Gateway
SOAP
Authorize includes only
Application one policy in
the effective
policy.
Conditional REST None. None. Yes. API

Error Gateway
SOAP
Processing includes all
Conditional
Error
Processing
policies in
the effective
policy.
Content- REST None. Straight No. API

based Through Gateway
SOAP
Routing Routing, includes only
Load one policy in
Balancer the effective
Routing, policy.
Dynamic
Routing,
M
Even Header
Policies

Policy an API?
Context-
based
Routing
Context- REST None. Straight No. API

based Through Gateway
SOAP
Load one policy in
Routing, policy.
Dynamic
Routing,
Content-
based
Routing
Custom REST None. None. No. API

HTTP Gateway
SOAP
Header includes only
one policy in
the effective
policy.
Data REST None. None. No. API

Masking Gateway
SOAP
includes only
(Error
one policy in
Handling)
the effective
policy.

Masking Gateway
SOAP
includes only
(Response
one policy in
Processing)
the effective
policy.

Masking Gateway
SOAP
includes only
(Request
one policy in
Processing)
M
Odd Header
Policies

Policy an API?
the effective
policy.
Dynamic REST None. Straight No. API

Routing Through Gateway
SOAP
Routing, includes only
Load one policy in
Routing, policy.
Content-
based
Routing,
Context-
based
Routing
Enable REST None. None. No. API

HTTP / Gateway
SOAP
HTTPS includes only
one policy in
the effective
policy.
Enable JMS / REST None None No. API

AMQP Gateway
SOAP
includes only
one policy in
the effective
policy.
Identify and REST None. None. No. API

Authorize Gateway
SOAP
Application includes only
one policy in
the effective
policy.
Inbound SOAP None. None. No. API

Authentication Gateway
- Message includes only
one policy in
M
Even Header
Policies

Policy an API?
the effective
policy.
Inbound REST None. None. No. API

SOAP
- Transport includes only
one policy in
the effective
policy.
Invoke REST None. None. Yes. API

webMethods Gateway
SOAP
IS includes
all Invoke
(Response
webMethods
Processing)
IS policies in
the effective
policy.
Invoke REST None. None. Yes. API

webMethods Gateway
SOAP
IS includes
all Invoke
(Request
webMethods
Processing)
IS policies in
the effective
policy.
JMS/AMQP REST JMS/ None No. API

Properties AMQP Gateway
SOAP
Routing includes only
one policy in
the effective
policy.
JMS/AMQP REST None Straight No. API

Routing Through Gateway
SOAP
Routing, includes only
Dynamic one policy in
Routing, the effective
Content- policy.
based
Routing,
M
Odd Header
Policies

Policy an API?
Context-
based
Routing
Load REST None. Straight No. API

Balancer Through Gateway
SOAP
Content- policy.
based
Routing,
Context-
based
Routing
Log REST None. None. Yes. API

Invocation Gateway
SOAP
includes all
Log Invocation
policies in
the effective
policy.
Monitor REST None. None. Yes. API

Service Gateway
SOAP
Performance includes
all Monitor
Service
Performance
policies in
the effective
policy.
Monitor REST Identify None. Yes. API

Service and Gateway
SOAP
Level Authorize includes
Agreement Application all Monitor
Service Level
Agreement
policies in
the effective
policy.
M
Even Header
Policies

Policy an API?
Outbound SOAP None. None. No. API

- Message includes only
one policy in
the effective
policy.
Outbound REST None. None. No. API

SOAP
- Transport includes only
one policy in
the effective
policy.
Response REST None. None. Yes. API

Transformation Gateway
SOAP
includes
all XSLT
Transformation
policies in
the effective
policy.
Request REST None. None. Yes. API

Transformation Gateway
SOAP
includes
all XSLT
Transformation
policies in
the effective
policy.
Service REST None. None. No. API

Result Gateway
SOAP
Cache includes only
one policy in
the effective
policy.
Set Media REST None. None. No. API

Type Gateway
includes only
one policy in
M
Odd Header
Policies

Policy an API?
the effective
policy.
Straight REST None. Load No. API

Through Balancer Gateway
SOAP
Content- policy.
based
Routing,
Context-
based
Routing
Throling REST Identify None. Yes. API

Traffic and Gateway
SOAP
Optimization Authorize includes all
Application Throling
Traffic
Optimization
policies in
the effective
policy.
Validate API REST None. None. No. API

Specification Gateway
SOAP
includes only
(Response
one policy in
Processing)
the effective
policy.
Validate API REST None. None. No. API

Specification Gateway
SOAP
includes only
(Request
one policy in
Processing)
the effective
policy.
M
Even Header
Policies
Managing Threat Protection Policies

Threat protection policies prevent malicious aacks on applications that typically
involve large, recursive payloads, and SQL injections. You can limit the size of things,
such as maximum message size, maximum number of requests, maximum node depth
and text node length, in the XML document.
The threat protection policies apply to an API globally for all requests coming into API
Gateway. These policies are executed only for requests coming to the external port of
API Gateway. You can configure the global threat protection rules to filter requests
that API Gateway receives. You can also configure API Gateway to send an alert when
a request violates a rule. When a rule is configured to send an alert and a violation
occurs, API Gateway logs the details and generates an alert. The alert message contains
detailed information that includes the IP address from which the request was sent, user
information, and the name of the rule filter that matched.
API Gateway applies rules in the order in which they are displayed on the Global
policies screen. Because a violation of a denial rule causes API Gateway to stop
processing a request, it is important to prioritize the rules based on the order in which
you want them to be evaluated. The server processes denial rules before alert rules.
You must have the API Gateway's manage threat protection functional privilege
assigned to perform this task.
Global Denial of Service
Denial of Service by IP
Rules
In addition, the API Gateway administrator can configure the necessary mobile devices
and applications, configure alert options, and manage the IPs that are denied access.
Note: If you have deployed API Gateway in a paired gateway deployment scenario
with multiple instances of API Gateway connected using a load balancer for
threat protection, when you make a change in enforced rules on one of the
API Gateway instances you have to restart the other instances to synchronize
the rule enforcement across all the API Gateway instances.
Configuring Global Denial of Service Policy

You can configure this policy in API Gateway to prevent Denial of Service (DoS) aacks.
One form of DoS aack occurs when a client floods a server with many requests in
an aempt to interfere with server processing. Using API Gateway, you can limit the
number of requests that API Gateway accepts within a specified time interval and the
number of requests that it can process concurrently. By specifying these limits, you can
protect API Gateway from DoS aacks.
M
Odd Header
Policies
You can configure API Gateway to consider the total number of requests from all IP
addresses, or to consider the number of requests from individual IP addresses. For
example, you might want to limit the total number of requests received to 10 requests
in 10 seconds, and limit the number of requests coming from any single IP address to
2 requests in 10 seconds. When API Gateway detects that a limit has been exceeded, it
sends an alert. Depending on your configuration, API Gateway can temporarily block
requests from all clients, or deny requests from particular IP addresses.
To configure global denial of service policy

1. Click Policies in the title navigation bar.
2. Select Threat protection > Global denial of service.
3. Set the Enable buon to the On position to enable the policy.
4. Type the maximum number of requests, in the Maximum requests field, that API
Gateway can accept from a specific IP address in a given time interval.
5. Specify time in seconds, in the In (seconds) field, in which the maximum requests
have to be processed.
6. Type the maximum number of requests, in the Maximum requests in progress field, that
API Gateway can process concurrently from any single IP address, .
7. Specify the time in minutes, in the Block intervals (minutes) field, for which you want
requests to be blocked.
8. Type the alert message text, in the Error message field, to be displayed when the
policy is breached.
9. Add IP addresses, in the Trusted IP addresses field, that can be trusted and are always
allowed.
API Gateway supports IPv4 and IPv6 addresses in the trusted IP addresses lists.
You can specify a range of IP addresses using the classless inter-domain routing
(CIDR) notation. To specify an IP address range, type the first IP address in the
range followed by a forward slash (/) and a CIDR suffix.
Example IPv4 address range:
192.168.100.0/22 represents the IPv4 addresses from 192.168.100.0 to
192.168.103.255
148.20.57.0/30 represents the IPv4 addresses from 148.20.57.0 to 148.20.57.3
f000::/1 represents the IPv6 addresses from f000:: to
ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff.
2001:db8::/48 represents the IPv6 addresses from 2001:db8:0:0:0:0:0:0 to
2001:db8:0:ffff:ffff:ffff:ffff:ffff.
M
Even Header
Policies
Click to add more than one IP address.
10. Click Save.
Configuring Denial of Service by IP Policy

This policy is configured to ensure that requests from trusted IPs are not denied. You
can configure a list of IP addresses so that requests from these IP addresses are always
allowed. You can configure a time interval for the maximum number of requests that
can be processed from an IP address or a range of IP addresses and when this limit of
maximum number is exceeded the IP is moved to the Denied IP List.
To configure the denial of service by IP policy

2. Select Threat protection > Denial of service by IP.
3. Set the Enable buon to the On position to enable the policy.
4. Type the maximum number of requests, in the Maximum requests field, that API
Gateway can accept from a specific IP address in a given time interval.
5. Specify time in seconds, in the In (seconds) field, in which the maximum requests
have to be processed.
6. Type the maximum number of requests, in the Maximum requests in progress field, that
API Gateway can process concurrently from any single IP address.
7. Select one of the following actions to be taken when the number of requests from a
non-trusted IP address exceeds the specified limits:
Add to deny list to permanently deny future requests from the IP address.
Block temporarily block requests from this IP address.
8. Type the alert message text, in the Error message field, to be displayed when the
policy is breached.
9. Add IP addresses, in the Trusted IP Addresses field, that can be trusted and not
blocked.
API Gateway supports IPv4 and IPv6 addresses in the trusted IP addresses lists.
You can specify a range of IP addresses using the classless inter-domain routing
(CIDR) notation. To specify an IP address range, type the first IP address in the
range followed by a forward slash (/) and a CIDR suffix
192.168.100.0/22 represents the IPv4 addresses from 192.168.100.0 to
192.168.103.255
148.20.57.0/30 represents the IPv4 addresses from 148.20.57.0 to 148.20.57.3
M
Odd Header
Policies

f000::/1 represents the IPv6 addresses from f000:: to
ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff.
2001:db8::/48 represents the IPv6 addresses from 2001:db8:0:0:0:0:0:0 to
2001:db8:0:ffff:ffff:ffff:ffff:ffff.
Click to add more than one IP address.
10. Click Save.
Managing Denied IP List

The Denied IPs section has a list of IPs that were denied access due to breach of one of
the policies for denial of service policies. You can delete the IP from the list and make it
available.
To manage the denied IP list

2. Select Threat protection > Denied IPs.
This displays a list of IPs or IP address range that were denied access.
3. Click in the Action column so that the specified IP can be made available.
Configuring Rules
You can configure rules to filter malicious requests based on message size, requests from
specific mobile devices and applications that could be harmful, requests that could cause
an SQL injection aack, or use custom filters to avoid malicious aacks.
The logs generated by the threat protection rules are logged under Security log in
Integration Server. This logging action is disabled by default, you have to enable it to
log the threat protection logs. For details on how to enable the this logging action in
Integration server, see webMethods Integration Server Administrator’s Guide.
To configure rules
2. Select Threat protection > Rules.
This displays a list of rules that are already configured.
3. Click Add rule.
4. In the Rule properties section provide the following information:
a. Type a name for the rule in the Rule name field.
M
Even Header
Policies
Valid rule names:

Must be unique.
Must not be empty.
Must not contain spaces.
Must not contain the special characters - ? ~ ` ! @ # $ % ^ & * ( ) - + = { } | [ ] \
\ : \" ; ' < > , /
b. Type a description for the rule in the Description field.
c. Select an action to be followed when the policy is violated:
Deny request and alert to deny the access and send an alert when the policy is
violated.
Alert to allow the request and send an alert when the policy is violated.
d. Type the alert message text, in the Error message field, to be displayed when the
policy is violated.
e. Select the required Request type to which you want to apply the rule and provide
the additional information required.
ALL: Applies the rule to all requests.
REST: Applies the rule to all REST requests.
SOAP: Applies the rule to all SOAP requests.
INVOKE: Applies the rule to all INVOKE requests.
CUSTOM: Applies the rule to all requests specified by the custom directives.
You can use this option if you want a single rule applied for multiple request
types and custom directives.
f. Provide the following information to filter the requests depending on the Request
type selected:
Resource path: Provide the Resource path for the REST, SOAP, INVOKE, or
CUSTOM Request type selected to filter the requests based on the resource
being requested. The format for the REST, SOAP, and INVOKE request types
is folder_name/service_name and the format for a CUSTOM request type
is given_directive/service_name. You can add multiple resource paths
using the Add buon.
Custom directives: Provide the custom directives for the CUSTOM Request
type to filter the incoming requests. For example, if you provide gateway as
the directive, the rule applies to all these requests that are received in API
Gateway with the directive gateway. You can add multiple directives using
the Add buon.
5. Configure the required filters as follows:
M
Odd Header
Policies
Alert settings. Select one of the following options:

Default: Sets the default alert seings to be used.
Custom: You can specify this option to use the custom alert seings and
provide the required information.
Alert destination: Specify the alert destination. Values are Email and Flow
service. If you select Email, provide the email ids to which the alert
notification has to be sent. If you select Flow service, a flow service is
invoked. Type pub.apigateway.threatProtection:violationListener that is used as the
signature of the flow service and provide the user who has permissions to
execute the service, for example, Administrator.
Send alert: Select a condition depending on when you want the alert to
be sent. Available values are On rule violation which sends an alert every
time a request violates a rule or Every and specify the time interval (in
minutes), which send alerts at specified intervals.
Message size filter
Set the Enable buon to the On position to enable the filter.
Type the maximum size allowed for HTTP and HTTPS requests in the
Maximum message size (MB) field.
If the request is larger than the size specified in this limit, the request violates
the rule and API Gateway performs the configured action.
OAuth filter
Set the Require OAuth credentials toggle buon to the On position. This implies
the request should contain the OAuth credentials else the request would be
denied.
Mobile application protection filter
You can configure this filter to disable access for certain mobile application
versions on a predefined set of mobile platforms. By disabling access to these
versions, you are ensuring that all users are using the latest versions of the
applications and taking advantage of the latest security and functional updates.
Select the device type.
Select the mobile application.
Select the operator condition =, >, <, >=, <= or <>.
Type the mobile application version.
You can add multiple entries by clicking .
M
Even Header
Policies
SQL injection protection filter

You can use the SQL injection protection filter to block requests that could
possibly cause an SQL injection aack. When this filter is enabled, API Gateway
checks each request message for specific paerns of characters or keywords that
are associated with potential SQL injection aacks. If a match is found in the
request parameters or payload, API Gateway blocks the request from further
processing.
Set the Enable buon to the On position to enable the selected filter.
Select the required filters as follows:
Select Database-specific SQL injection protection and select a database against
which specific parameters needs to be checked.
When enabled, API Gateway checks the incoming payload based on the
specified database and GET or POST request parameters. If no parameter
is specified, all input parameters are checked for possible SQL injection
aack.
Select Standard SQL injection protection and specify one or more GET or
POST request parameters that could be present in the incoming requests.
Parameters can contain only alphanumeric characters, dollar sign ($), and
underscore (_).
Anti virus scan filter

You can use the antivirus scan filter to configure API Gateway to interact with an
Internet Content Adaptation Protocol (ICAP)-compliant server. An ICAP server
is capable of hosting multiple services that you can use to implement features
such as virus scanning or content filtering. Using the antivirus scan filter, API
Gateway can leverage the ICAP protocol to scan all incoming HTTP requests and
payloads for viruses.
Type the antivirus ICAP engine name in the ICAP name field.
Type the host name or IP address of the machine on which the ICAP server is
running in the ICAP host name or IP address field.
Type the port number on which the ICAP server is listening in the ICAP port
number field.
Type the name of the service exposed by the ICAP server that you can use to
scan your payload for viruses in the ICAP service name field.
JSON threat protection filter
You can use this filter to block aacks through JSON payload that have infinitely
long strings or deeply nested payloads. Software AG recommends that this
M
Odd Header
Policies
protection should be combined with message size filter to identify infinite

payloads.
You can specify any of these parameters as filter criteria. If you do not specify a
value, the system applies a default value of -1, which means an unlimited value.
Field Description
Container depth Specifies the maximum allowed containment depth,

where the containers are objects or arrays.
For example, an array containing an object which
contains an object would result in a containment
depth of 3.
Object entry count Specifies the maximum number of entries allowed in

an object.
Object entry name Specifies the maximum string length allowed for a
length field property name within an object.
Array element count Specifies the maximum number of elements allowed

in an array.
String value length Specifies the maximum length allowed for a string
value.
Applicable content Specify any other content types to be included in the

type filter.
You can add more entries by clicking .
XML threat protection filter

You can use this filter to block aacks through XML payload that have infinitely
long strings or deeply nested payloads. Software AG recommends that this
protection should be combined with message size filter to identify infinite
payloads.
You can specify any of these parameters as filter criteria. If you do not specify a
value, the system applies a default value of -1, which the system equates to no
limit.
M
Even Header
Policies
Field Description
Namespace prefix Specifies a limit on the maximum number of

length characters permied in the namespace prefix in the
XML document.
Namespace URI Specifies a character limit for any namespace URIs

length present in the XML document.
Namespace count Specifies the maximum number of namespace

per element definition allowed for any element.
Child count Specifies the maximum number of child elements

allowed for any element.
Attribute name Specifies a limit on the maximum number of

length characters permied in any aribute name in the
XML document.
Attribute value length Specifies a limit on the maximum number of

characters permied in any aribute value in the
XML document.
Attribute count per Specifies the maximum number of aributes allowed

element for any element.
Element name length Specifies a limit on the maximum number of

characters permied in any element name in the
XML document.
Text length Specifies a character limit for any text node present
in the XML document.
Comment length Specifies a character limit for any comments present

in the XML document.
Processing Specifies a limit on the maximum number of

instruction target characters permied in the target of any processing
length instructions in the XML document.
Processing Specifies a limit on the maximum number of

instruction data characters permied in the data value of any
length processing instructions in the XML document.
M
Odd Header
Policies
Field Description
Node depth Specifies the maximum node depth allowed in the

XML.
Applicable content Specify any other content types to be included in the

types filter.
You can add multiple values by clicking .
Custom filter
You can use the custom filter to invoke a service that is available on API Gateway
to perform actions such as custom authentication of external clients in the
DMZ, logging or auditing in the DMZ, or implementation of custom rules for
processing various payloads.
Click Browse and select a service to invoke it.
Select the user name of a user you want API Gateway to run the service. The
default value is Administrator.
6. Click Save.
The new rule is created and appears in the list of rules in the Rules page.
The rule is applied to requests only if the rule is enabled. You can enable the rule in the
Rules page by selecting the enable icon for the required rule.
Registering a Mobile Device or Application

You can use API Gateway to disable access for certain mobile application versions on a
predefined set of mobile platforms. By registering the required devices and applications
and disabling access to these versions, you ensure that all users use the latest versions of
the applications and take advantage of the latest security and functional updates.
To register a mobile device or application

2. Select Global Policies > Mobile devices and apps.
3. Provide the mobile device type name and click .
You can add more entries by clicking . You can delete the added ones by
clicking .
4. Provide the mobile application name and click .
M
Even Header
Policies
You can add more entries by clicking . You can delete the added ones by
clicking .
5. Click Save.
Configuring Alert Settings

You can configure the alert seings to control the following aspects of alerts that API
Gateway sends when a request violates a rule:
Whether API Gateway issues an alert for a rule violation.
How often API Gateway issues the alert.
The method API Gateway uses to send the alert.
Whether a rule uses the default alert options or its own customized alert options.
To configure alert settings

2. Select Global Policies > Alert settings.
3. Select one or both the alert destination types:
Email. This sends email alerts.
Type the email ids to which the email has to be sent.
Flow Service. This invokes a flow service to alert you of a rule violation.
Type pub.apigateway.threatProtection:violationListener that is used as the signature of
the flow service.
Provide Administrator as the user type.
4. Select one of the following conditions depending on when you want the alert to be
sent.
On rule violation to send an alert every time a request violates a rule,
Every and specify the time interval (in minutes) to send to send alerts at specified
intervals.
5. Click Save.
System-defined Stages and Policies

API Gateway provides system-defined policies that are grouped into stages depending
on their usage:
Transport
M
Odd Header
Policies
Identify & Access

Request Processing
Routing
Traffic Monitoring
Response Processing
Error Handling
Transport
The policies in this stage specify the protocol to be used for an incoming request and the
content type for a REST request during communication between API Gateway and an
application. The policies included in this stage are:
Enable HTTP/HTTPS
Set Media Type
Enable HTTP/HTTPS
This policy specifies the protocol to use for an incoming request to the API on API
Gateway. If you have a native API that requires clients to communicate with the server
using the HTTP and HTTPS protocols, you can use the Enable HTTP or HTTPS policy.
This policy allows you to bridge the transport protocols between the client and API
Gateway.
For example, you have a native API that is exposed over HTTPS and an API that receives
requests over HTTP. If you want to expose the API to the consumers of API Gateway
through HTTP, then you configure the incoming protocol as HTTP.
The table lists the properties that you can specify for this policy:
Protocol Specifies the protocol (HTTP or HTTPS) and SOAP format

(for a SOAP-based API) to be used to accept and process
the requests.
HTTP. API Gateway accepts requests that are sent using
the HTTP protocol. This is selected by default.
HTTPS. API Gateway accepts requests that are sent using
the HTTPS protocol.
SOAP Version For SOAP-based APIs.
M
Even Header
Policies
Specifies the SOAP version of the requests which the API

Gateway accepts from the client.
SOAP 1.1. This is selected by default. API Gateway accepts
requests that are in the SOAP 1.1 format.
SOAP 1.2. API Gateway accepts requests that are in the
SOAP 1.2 format.
Set Media Type

This policy specifies the content type for a REST request. If the content type header is
missing in a client request sent to an API, API Gateway adds the content type specified
here before sending the request to the native API.
Default Content- Specifies the default content type for REST request
Type received from a client.
Examples for content types: application/json,
application/xml.
Default Accept Specifies the default accept header for REST request
Header received from a client.
Identify and Access

The policies in this stage provide different ways of identifying and authorizing the
application, and provide the required access rights for the application. The policies
included in this stage are:
Inbound Authentication - Message
Authorize User
Identify and Authorize Application
The Inbound authentication policies are used to authenticate the application by
specifying user-based SPN or host-based SPN for a Kerberos token, using the basic
credentials for the HTTP basic authentication or through various token assertions or
through the XML security actions.
M
Odd Header
Policies
The Authorize User policy authorizes the application against a list of users and a list of
groups registered in API Gateway.
The Identify and Authorize Application policy is used to identify the application,
authenticate the request based on policy configured and authorizes it against all
applications registered in API Gateway.
Inbound Authentication - Message

An API Provider can use this policy to enforce authentication on the API. When
this policy is configured for an API, API Gateway expects the clients to pass the
authentication credentials through the payload message that will be added to the
request and sent to the native API. API Gateway supports a wide range of authentication
schemes, such as X.509 Certificate, WSS Username, SAML, and Kerberos, in addition to
signing and encryption, at the message-level.
Note: Message-level authentication can be used to secure inbound communication

of only SOAP APIs.
Binding Assertion Specifies the type of binding assertion required for

the message transfer between the recipient and the
initiator.
Require Encryption. Specifies that a request's XML element, which is represented

by an XPath expression or by parts of a SOAP request such as the SOAP body or
the SOAP headers, be encrypted.
Encrypted Parts Click + Add encrypted part to add the required

properties. This allows you to encrypt parts of a SOAP
request such as the SOAP body or the SOAP headers.
Entire SOAP Body. Specifies encryption of the entire
SOAP body.
All SOAP Attachments. Specifies encryption of all the
SOAP aachments.
In the SOAP Header section, provide the following
information:
Header Name. Specifies the name for the SOAP header
field.
M
Even Header
Policies
Header Namespace. Specifies the namespace of the

SOAP header to be encrypted.
You can add more SOAP headers by clicking .
Encrypted Elements Click + Add encrypted element to add the required

properties. Select this option to encrypt the entire
element, which is represented by an XPath expression.
XPath. Specifies the XPath expression in the API
request.
In the Namespace section, provide the following
information:
Namespace Prefix. Specifies the namespace prefix of the
element to be encrypted.
Namespace URI. Specifies the generated XPath element.
You can add more namespace prefixes and URIs by
clicking .
Require Signature. Specifies that a request's XML element, which is represented by

an XPath expression or by parts of a SOAP request such as the SOAP body or the
SOAP headers, be signed.
Signed Elements Click + Add require signature to add the required

properties. Select this option to sign the entire element
represented by an XPath expression.
XPath. Specifies the XPath expression in the API
request.
For the Namespace section, provide the following
information:
Namespace Prefix. Specifies the namespace prefix of the
element to be signed.
Namespace URI. Specifies the generated XPath element.
M
Odd Header
Policies

clicking .
Signed Parts Click + Add signed part to add the required properties.
Select this option to sign parts of a SOAP request such
as the SOAP body or the SOAP headers.
Entire SOAP Body. Specifies signing of the entire SOAP
body.
All SOAP Attachments. Specifies signing of all the SOAP
aachments.
For the SOAP Header section, provide the following
information:
Header Name. Specifies the name for the SOAP header
field.
Header Namespace. Specifies the Namespace of the
SOAP header to be signed.
clicking .
Match Criteria Select one of the following options:

Allow Sublevels. Any one of the audience URI in the
incoming SAML assertion either has to be an exact
match or it can have sub paths to the configured URI.
For example, if http://yahoo.com is configured as
the URI and the Allow Sublevels option is selected, the
audience URI has http://yahoo.com/mygroup and
condition is matched because the main URI matches
with the configured URI (http://yahoo.com). The
extra path mygroup is a sublevel path.
Exact match. Any one of the audience URI in the
incoming SAML assertion is verified for the exact
match with the configured URI. For example, if
http://yahoo.com is configured as the URI and the
Exact match option is selected, the audience URI must
be configured with http://yahoo.com in order to
match the condition. This is selected by default.
M
Even Header
Policies
For more information on audience URI, see conditions

and audience restriction sections in the SAML
specification available in the “hps://docs.oasis-
open.org/security/saml/v2.0/saml-core-2.0-os.pdf”
location.
Token Assertions Select the type of token assertion required to

authenticate the client.
Select any of the following:
Require X.509 Certificate. Mandates that there should be
a wss x.509 token in the incoming SOAP request.
Require WSS Username token. Mandates that there
should be a WSS username token in the incoming
SOAP request. Uses WS-Security authentication
to validate user names and passwords that are
transmied in the SOAP message header for the WSS
Username token.
Kerberos Token Authentication. Mandates that there
should be a Kerberos token in the incoming SOAP
request. Authenticates the client based on the
Kerberos token. API Gateway extracts the Kerberos
token from the SOAP body and validates the token
with the KDC using SPN credentials configured by
the provider for the API. If the Kerberos token sent by
the client is valid, API Gateway forwards the request
to the native service and the response to the client.
Service Principal Name. Specifies a valid SPN, which
is the name type to use while authenticating an
incoming client principal name. The specified
value is used by the client or the server to obtain a
service ticket from the KDC server.
Note:API Gateway supports the username format

for Service Principal Names (SPNs). This
format represents the principal name as
a named user defined in LDAP used for
Service Principal Password. Specifies a valid

password of the Service Principal Name user or
the Service Principal Name host.
Custom Token Assertion. Type a search string, select
a custom token assertion name to authenticate the
M
Odd Header
Policies
client, and click to add. You can add more custom
token assertions in a similar way.
Click the Custom Token Assertion arrow to see a list of
all custom token assertions available in API Gateway.
Click to delete the custom token assertion added.
Require Timestamp Specifies that the time stamps be included in the

request header. API Gateway checks the time stamp
value against the current time to ensure that the
request is not an old message. This serves to protect
your system against aempts at message tampering,
such as replay aacks.
Identify and Authorize Application

This policy authorizes and allows access to the applications that are trying to access the
APIs, for example, through IP address or hostname, and validate the clients credentials.
Condition Specifies the condition operator for the identification

and authentication types.
Select any of the following condition operators:
AND. Applies all the identification and authentication
types.
OR. Applies one of the selected identification and
authentication types.
Note: Even though this policy provides the option

of choosing an AND or OR operation between
the different identification and authentication
types, the operation across the different
policies in the IAM stage is always AND. For
example, configuring the Identify and Authorize
Application policy with API Key and the Inbound
Authentication - Transport policy with HTTP
Basic Authentication using an OR operation is not
supported.
M
Even Header
Policies
Allow anonymous Specifies whether to allow all users to access the API
without restriction.
When you add a security policy and configure Allow
anonymous, all requests are allowed to pass through
to the native API, but the successfully identified
requests are grouped under the respective identified
application, and all unidentified requests are grouped
under a common application named unknown. While
you allow all requests to pass through you can perform
all application-specific actions, such as, viewing the
runtime events for a particular application, monitor
the service level agreement for a few applications and
send an alert email based on some criteria like request
count or availability, and throle the requests from a
particular application and not allow the request from
that application if the number of requests reach the
configured hard limit within configured period of time.
Identification Type. Specifies the identification type. You can select any of the
following.
API Key Specifies using the API key to identify and validate
the client's API key to verify the client's identity in the
registered list of applications for the specified API.
Hostname Address Specifies using host name address to identify the client,
extract the client's hostname from the HTTP request
header and verify the client's identity in the specified
list of applications in API Gateway.
Select one of the Application Lookup condition:
Registered applications. Tries to verify the client's
hostname against a list of registered applications for
the specified API.
Global applications. Tries to verify the client's hostname
against a list of all global applications available in API
Gateway.
Note: If JMS is selected as the entry protocol policy,

extract the client's hostname from the X-
Forwarded-For JMS message property.
M
Odd Header
Policies
HTTP Basic Specifies using Authorization Header in the request to

Authentication identify and authorize the client application against the
list of applications with the identifier username in API
Gateway.
Registered applications. Tries to verify the
client's credentials against the list of registered
applications for the specified API.
Global applications. Tries to verify the client's
credentials against a list of all global applications
Do not identify. Checks for the existence of the
criterion but does not validate if the specified
value is a valid application and forwards the
request to the native API. For example, HTTP
Basic Authentication is checked by the HTTP
transport level property Authorization: Basic
Base64encodesusernamepassword
Note: You can use the username for further processing

using the request transformation policy.
IP Address Range Specifies using the IP address range to identify the

client, extract the client's IP address from the HTTP
request header, and verify the client's identity against
the specified list of applications in API Gateway.
credentials against a list of registered applications for
the specified API.
credentials against a list of all global applications
Note: If JMS is selected as the entry protocol policy,

extract the client's IP address from the X-
Forwarded-For JMS message property.
JWT Specifies using the JSON Web Token (JWT) to identify

the client, extract the claims from the JWT and
M
Even Header
Policies
validate the client's claims, and verify the client's
identity against the specified list of applications in API
Gateway.
Registered applications. Tries to verify the JWT against a
list of registered applications for the specified API.
Global applications. Tries to verify the JWT against a list
of all global applications available in API Gateway.
Note: You can use the claims in the JWT for further
processing using request transformation policy.
Kerberos Token Specifies using the Kerberos token to identify the client,
extract the client's credentials from the Kerberos token,
and verify the client's identity against the specified list
of applications in API Gateway.
Registered applications. Tries to verify the Kerberos
token against a list of registered applications for the
specified API.
Global applications. Tries to verify the Kerberos token
Gateway.

OAuth2 Token Specifies using the OAuth2 token to identify the client,
extract the client's credentials from the HTTP request
header, and verify the client's identity against the
specified list of applications in API Gateway.
Note: You can use the client id and other parameters

for further processing using the request
transformation policy.
OpenID Connect Specifies using the OpenID (ID) token to identify the
client, extract the client's credentials from the ID token,
and verify the client's identity against the specified list
of applications in API Gateway.
M
Odd Header
Policies
Registered applications. Tries to verify the ID token

against a list of registered applications for the
specified API.
Global applications. Tries to verify the ID token against
a list of all global applications available in API
Gateway.
Note: You can use the client id and other parameters

for further processing using the request
transformation policy.
SSL Certificate Specifies using the SSL certificate to identify the client,
extract the client's identity certificate, and verify the
client's identity (certificate-based authentication)
against the specified list of applications in API
Gateway. The client certificate that is used to identify
the client is supplied by the client to API Gateway
during the SSL handshake over the transport layer.
Registered applications. Tries to verify the client
certificate against a list of registered applications for
the specified API.
Global applications. Tries to verify the client certificate
Gateway.
WS Security Username This is applicable only for SOAP APIs.

Token
Specifies using the WS security username token to
identify the application, extract the client's credentials
(username token and password) from the WSSecurity
SOAP message header, and verify the client's identity
against the specified list of applications in API
Gateway.
WSS username token against a list of registered
Global applications. Tries to verify the client's WSS
username token against a list of all global applications
M
Even Header
Policies

WS Security X.509 This is applicable only for SOAP APIs.

Certificate
Specifies using the WS security X.509 certificate to
identify the client, extract the client identity certificate
from the WS-Security SOAP message header, and
verify the client's identity against the specified list of
applications inAPI Gateway.
Registered applications. Tries to verify the client's X.509
certificate against a list of registered applications for
the specified API.
Global applications. Tries to verify the client's X.509
certificate against a list of all global applications
Payload Element Specifies using the payload identifier to identify the

client, extract the custom authentication credentials
supplied in the request represented using the payload
identifier, and verify the client's identity against the
specified list of applications in API Gateway.
OAuth access token against a list of registered
identify credentials against a list of all global
applications available in API Gateway.
In the Payload identifier section, click Add payload
identifier, provide the following information, and click
Add.
Expression type: Specifies the type of expression,
which is used for identification. You can select one the
following expression type:
XPath. Provide the following information:
Payload Expression. Specifies the payload
expression that the specified expression type
M
Odd Header
Policies
in the request has to be converted to. For
example: /name/id
Namespace Prefix. The namespace prefix of the
payload expression to be validated.
Namespace URI. The namespace URI of the
Note:You can add multiple namespace prefix and

URI by clicking .
JSONPath. Provide the JSONPath for the payload

identification. For example, $.name.id
Text. Provide the regular expression for the
payload identification. For example, any valid
regular expression.
You can add multiple payload identifiers as required.
Note: Only one payload identifier of each type is

allowed. For example, you can add a maximum of
three payload identifiers, each being of a different
type.
Request Processing
These policies are used to specify how the request message from an application has to
be transformed or pre-processed and configure the masking criteria for the data to be
masked before it is submied to the native API. This is required to protect the data and
accommodate differences between the message content that an application is capable of
submiing and the message content that a native API expects. The policies included in
this stage are:
Request Transformation
Data Masking
This policy pre-processes the request messages and transforms the message into the
format required by the native API or performs some custom logic, before API Gateway
sends the requests to the native APIs.
M
Even Header
Policies
For example, you might need to accommodate differences between the message content
that a client is capable of submiing and the message content that a native API expects.
For example, if the client submits an order record using a slightly different structure
than the structure expected by the native API, you can use this action to process the
record submied by the client to the structure required by the native API.
If Comply to IS Spec parameter is configured as true, API
Gateway invokes the IS Service with IS specification in the path
pub.apigateway.invokeISService.specifications:RequestSpec for Request Processing
The following are the input and output parameters for REST and SOAP APIs as
specified in the above IS Specification.
API type Input parameters Output parameters
REST headers headers

query query
payload payload
path path
hpMethod hpMethod
messageContext messageContext
apiName
requestUrl
correlationID (this is unique
for request and response)
SOAP headers headers

payload payload
apiName payloadObject
payloadObject
requestUrl
correlationID (this is unique
for request and response)
Note: For SOAP to REST APIS, the payload contains the transformed SOAP
request.
In the 10.2 release, payload transformation does not happen automatically
for content-type transformation. When you change the content type,
ensure to do payload transformation also as part of IS Service. For
M
Odd Header
Policies
example, if you change the content-type header from application/xml to

application/json using IS service, you must also change the respective
payload from application/xml to application/json
Only Method Transformation happens when configured, but you have
to take care of adding payload during transformations involving method
change like GET to POST, and so on.
When Comply to IS spec is true, you can change the values of headers,
query, payload, and so on, programatically using Message Context, as
well as using the pipeline variables given. Software AG recommends you
do not change those values directly in Message Context, as the values
in output pipeline variables are wrien to Message Context after the
invocation of IS Service.
If Comply to IS Spec parameter is set to false, API Gateway invokes the IS Service
with the same input and output parameters supported in 10.1 and the earlier versions:
proxy.name
JSONRESTContentString (REST only)
SOAPEnvelope (SOAP only)
EnvelopeString (SOAP only)
Invoke webMethods Integration Server Service
Add invoke Specifies the webMethods IS service to be invoked to

webMethods pre-process the request messages and the authentication
Integration Server mode for the IS service.
service
webMethods IS Service. Specify the webMethods IS
service to be invoked to pre-process the request
messages. The list displays only the pre-shipped
Integration Server services, which you can invoke to
pre-process or post-process the request message.
Run as User. Specifies the authentication mode to
invoke the IS service. If this field is left blank the
incoming credentials of the user, identified by API
Gateway, are used to authenticate and invoke the IS
service. You can also specify a particular user, you
want API Gateway to invoke the IS service.
M
Even Header
Policies
Note: It is the responsibility of the user who activates

the API to review the value configured in Run as
User field to avoid misuse of this configuration.
Comply to IS Spec. Mark this as true if you

want the input and the output parameters
to comply to the IS Spec present in
pub.apigateway.invokeISService.specifications folder
in wmAPIGateway package.
Note: Software AG recommends users to configure the

policy with Comply to IS Spec as true, as you
can read or change the values of headers, and so
on, without having to read from or write to the
message context.
webMethods IS Specifies the webMethods IS service alias to be invoked

Service alias to pre-process the request messages.
Start typing the webMethods alias name, select the alias
from the type-ahead search results displayed and click
to add one or more aliases.
You can use the delete icon to delete the added

aliases from the list.
Request Transformation
This policy enables you to configure several transformations on the request messages
from clients into a format required by the native API before it is submied to the native
API.
The transformations include Header, Query Parameter, Path Parameter transformation,
HTTP Method transformation, Payload transformation, and Advanced transformation.
You can configure conditions according to which the transformations are executed.
API Gateway supports the following parameter types that can be used to configure the
transformation policy:
request.headers
jms.headers
request.query.QUERY_NAME (applicable only for REST API)
request.path(applicable only for REST API)
request.path.regex[Expression] (applicable only for REST API)
M
Odd Header
Policies
request.hpmethod (applicable only for REST API)

request.headers.HEADER_NAME
request.authorization.clientId
request.authorization.claims.CLAIM_NAME
request.authorization.userName
jms.query.QUERY_NAME (applicable only for REST API)
jms.path (applicable only for REST API)
jms.hpmethod (applicable only for REST API)
jms.path.regex[Expression] (applicable only for REST API)
jms.headers.HEADER_NAME (applicable only for REST API)
The parameter types that are of the format jms.xxx are used when you want to use JMS/
AMQP so that transformation can be applied for the jms/amqp values
API Gateway supports the following Query types that can be used to configure the
xpath
jsonPath
regex
When you use these syntaxes to extract a value from the payload, the content-types
applicable are:
${payload.jsonPath} - application/json, application/json/badgerfish
${payload.regex} - text/plain
${payload.xpath} - application/xml, text/xml, text/html.
Condition Conditions are used to specify when the policy has to be

executed. You can add multiple conditions with logical
operators.
AND. API Gateway transforms the requests that comply
with all the configured conditions.
OR. This is selected by default. API Gateway transforms
the requests that comply with at least one configured
condition.
M
Even Header
Policies
Click Add Condition and provide the following information

and click .
Variable: Specifies the variable type with a syntax as

follows:
${PARAMTYPE} : This is applicable for variables of
string type - path, payload, hpMethod. For example:
${request.path}
${PARAMTYPE.paramName} : This is applicable for
map types - query and headers and also applicable
for path. For example: ${request.query.var1},
${request.header.Content-Type},
${request.path.name}
${PARAMTYPE.QUERYTYPE[queryValue]} : This
syntax is applicable for payload and path. regex can
be applied on path while XPath, JSONPath and regex
can be applied on payload. For example:
${request.payload.xpath[//ns:emp/
ns:empName]} where //ns:emp/ns:empName is the
xpath to be applied on the payload if contentType is
application/xml
${request.payload.jsonPath[$.cardDetails.number]}
where $.cardDetails.number is the jsonPath to be
applied on the payload if contentType is application/
json
${request.payload.regex[[0-9]+]} where [0-9]+ is
the regex to be applied on the payload if contentType
is text/plain
If you want API Gateway to apply xpath,
jsonPath, regex based on Content-Type of the
payload, use the following common syntax:
${PARAMTYPE.QUERYTYPE[queryValue] ||
PARAMTYPE.QUERYTYPE2[queryValue2] || ...}
For example:
${request.payload.xpath[//
ns:emp/ns:empName] ||
request.payload.jsonPath[$.cardDetails.number]}
This applies xpath for application/xml and jsonPath
for application/json
M
Odd Header
Policies
request.payload.jsonPath[$.cardDetails.number]
|| request.payload.regex[[0-9]+]} This applies
xpath for application/xml, jsonPath for application/
json, and regex for text/plain.
Operator: Specifies the operator to use to relate variable
and the value provided. You can select one of the
following:
Equals
Equals ignore case
Not equals
Contains
Exists
Value: Specifies a value with a syntax as follows:
PLAIN VALUE, for example, application/json
${PARAMTYPE.paramName}
${PARAMTYPE.QUERYTYPE[queryValue]}
Transformation Configuration: Specifies various transformations to be configured.
Header/ Specifies the Header, Query or path transformation to be

Query/Path configured for incoming requests.
Transformation
You can add or modify header, query or path
for REST API
transformation parameters by providing the following
and information:
Header Variable. Specifies the variable type with a syntax as
Transformation follows:
for SOAP API
${PARAMTYPE}. This is applicable for variables of
string type - path, payload, hpMethod. For example:
${request.path}
${PARAMTYPE.paramName}. This is applicable for
map types - query and headers and also applicable
for path. For example: ${request.query.var1},
M
Even Header
Policies
${request.header.Content-Type},
${request.path.name}
${PARAMTYPE.QUERYTYPE[queryValue]}. This syntax

is applicable for payload and path. regex can be
applied on path while XPath, JSONPath and regex can
be applied on payload. For example:
${request.payload.xpath[//ns:emp/
application/xml
${request.payload.jsonPath[$.cardDetails.number]}
xml
${request.payload.regex[[0-9]+]} where [0-9]+ is
the regex to be applied on the payload if contentType
is anything
For example:
request.payload.jsonPath[$.cardDetails.number]}
request.payload.jsonPath[$.cardDetails.number]
|| request.payload.regex[[0-9]+]} This applies
json, and regex for text/xml.
Note: The parameter types that are of the format jms.xxx

are used when you want to use JMS/AMQP so
that transformation can be applied for the jms/
amqp values. For example, if you have set the path
parameter as jms.path.petid and the corresponding
value as jms.header.h1, then if the request contains
M
Odd Header
Policies
the header value h1, the value h1 is replaced by the
path parameter petid.
Value. Specifies a value with a syntax as follows:

You can add multiple variables and corresponding values
by clicking .
You can remove any header, query or path transformation

parameters by typing the value in the text box.
Note: In the 10.2 release, payload transformation does not

happen automatically for content-type transformation.
When you change the content type, ensure to do
payload transformation also as part of IS Service. For
example, if you change the content-type header from
application/xml to application/json using IS service,
you must also change the respective payload from
application/xml to application/json
Method Specifies the method transformation to be configured for

transformation for incoming requests.
REST API
Select any of the HTTP Method listed:
GET
POST
PUT
DELETE
HEAD
CUSTOM
Note: When CUSTOM is selected, the HTTP method in

incoming request is sent to the native service. When
other methods are selected, the selected method is
used in the request sent to the native service.
M
Even Header
Policies
Note: Only Method Transformation happens when

configured, but you have to take care of adding
payload during transformations involving method
Payload Specifies the payload transformation to be configured for

Transformation incoming requests.
Click + Add xslt document to add an xslt document and
XSLT file. Specifies the XSLT file used to transform the
request messages as required.
Click Browse to browse and select a file.
Feature Name. Specifies the name of the XSLT feature.
Feature value. Specifies the value of the XSLT feature.
You can add more XSLT features and xslt documents
by clicking .
Click + Add xslt transformation alias and provide the

XSLT Transformation alias. Specifies the XSLT
transformation alias
Advanced Specifies the advanced transformation to be configured for

Transformation incoming requests.
webMethods IS Service. Specify the webMethods IS service
to be invoked to process the request messages. The list
displays only the pre-shipped Integration Server services,
which you can invoke to pre-process or post-process the
request message.
You can add multiple services by clicking .
Run as User. Specifies the authentication mode to invoke

the IS service. If this field is left blank the incoming
credentials of the user, identified by API Gateway, are
used to authenticate and invoke the IS service. You can
M
Odd Header
Policies
also specify a particular user, you want API Gateway to
use to invoke the IS service.
Comply to IS Spec. Mark this as true if you want the input
and the output parameters to comply to the IS Spec
present in pub.apigateway.invokeISService.specifications
folder in wmAPIGateway package.
webMethods IS Service alias. Specifies the webMethods IS
service alias to be invoked to pre-process the request
messages.
Transformation Metadata: Specifies the metadata for transformation of the incoming

requests. For example, the namespaces configured in this section can be used
when you provide the syntax for XPath ${request.payload.xpath} For example:
${request.payload.xpath[//ns:emp/ns:empName]}
Namespace Specifies the namespace information to be configured for

transformation.
Namespace Prefix. The namespace prefix of the payload
expression to be validated.
Namespace URI. The namespace URI of the payload
Note: You can add multiple namespace prefix and URI

by clicking .
Validate API Specification

This policy validates the incoming request against API's various specifications such
as schema, query parameters, path parameters, content-types, and HTTP Headers
referenced in their corresponding formats as follows:
The schema is available as part of the API definition. The schema for SOAP API are
imported through WSDL and for REST APIs it can be through swagger, RAML or
can be uploaded by the user.
The query parameters, path parameters and content- types are available as part of
the API definition.
The HTTP Headers are specified in the Validate API Specification policy page
M
Even Header
Policies
The request sent to the API by an application must conform with the structure or format
expected by the API. The incoming requests are validated against the API specifications
in this policy to conform to the structure or format expected by the API.
Various API specifications validated are:
Schema:
The incoming requests are validated against the schema provided in the API
definition. The schema defines the elements and aributes and specifies the data
types of these elements to ensure that only appropriate data is allowed through to
the API.
For a REST API, the schema can be added inline or uploaded in the Technical
Information section on the API Details page. The validation depends on the Content-
type header in the request or Accept header in the response and the corresponding
schema validation would be executed. The default Content type/Accept header and
schema validation type mapping is as follows:
Content-type/Accept Schema validation type
application/json JSON schema

application/json/
badgerfish
application/xml XML schema

text/xml
text/html
text/plain Regex schema
For a SOAP API, the WSDL and the referenced schema must be provided in a zip
format. The JSON schema validation is supported for the operations that are exposed
as REST.
Note: If schema mapping is not found for a content-type of the request in the
API, the behavior is as follows:
If schema mapping is not available in a REST API or SOAP-to-REST
transformed API, the validation is skipped.
If application/json is mapped to XML schema in the API definition,
then the JSON content in the request is validated against XML schema
to provide a backward compatibility support for APIs migrated from
the 10.1 version.
If only XML schema mappings exist for any of the content-types,
the payload is converted into XML and validated against all the
M
Odd Header
Policies
XML schemas. If the payload is valid against one of the schemas, the
validation is successful.
If the payload is not XML convertible, the validation is not performed
and the request is allowed to reach the native API.
Query Parameters:
This is applicable only for a REST API. The incoming requests are validated against the
query parameters specified in the API definition.
Path Parameters:
This is applicable only for a REST API. The incoming requests are validated against the
path parameters specified in the API definition.
Content-types:
The incoming requests are validated against the content-types specified in the API
definition.
Note: When Content-type validation is selected for a SOAP API, the validation
fails in case of SOAP to REST scenarios and displays an error with 500
status code instead of 400 as displayed in the other scenarios.
when we have Content type validation selected for SOAP API,when SOAP TO REST
scenarios , this validation will not happen i.e An error will be thrown wi h 500 status
code and not 400 as the other scenarios
HTTP Headers:
The incoming requests are validated against the HTTP Headers specified in this
policy to conform to the HTTP headers expected by the API.
The runtime invocations that fail the specification validation are considered as policy
violations. You can view such policy violation events in the dashboard.
The table lists the API specification properties, you can specify for this policy, to be
validated:
Schema Validates the request payload against the appropriate

schema (based on the Content-type header in request or
Accept header in response).
Provide the following additional features for XML schema
validation:
Feature name. Specifies the name for the schema
configuration.
For example: TOLERATE_DUPLICATES,
NAMESPACE_GROWTH
M
Even Header
Policies
Feature value. Specifies whether the feature value is True or

False.
Query Parameters This is applicable only for a REST API. Validates the query
parameters in the incoming request against the query
parameters defined in that request's API Specification. The
configuration is provided in the API details page.
Path Parameters This is applicable only for a REST API. Validates the path
parameters in the incoming request against the path
parameters defined in that request's API Specification. The
configuration is provided in the API details page.
Content-types Validates the content-types in the incoming request

against the content-types defined in that request's API
Specification. The configuration is provided in the API
details page.
HTTP Headers Validates the HTTP header parameters in the incoming

request against the HTTP headers defined in that request's
API Specification. The configuration is provided in the API
details page.
Condition. Specifies the logical operator to use to validate
multiple HTTP headers in the incoming API requests.
AND. API Gateway accepts only the requests that
contain all configured HTTP headers.
OR. This is selected by default. API Gateway accepts
requests that contain at least one configured HTTP
header.
HTTP Header Key. Specifies a key that must be passed
through the HTTP header of the incoming API requests.
Header Value. Optional. Specifies the corresponding key
value that could be passed through the HTTP header of
the incoming API requests.
The Header Value field type accepts string and regular
expression (regex).
M
Odd Header
Policies
You can add more HTTP headers by clicking .
Data Masking
Data masking is a technique whereby sensitive data is obscured in some way to render
it safe and to protect the actual data while having a functional substitute for occasions
when the real data is not required.
This policy is used to mask sensitive data at the application level. At the application level
you must have an Identify and Access policy configured to identify the application for
which the masking is applied. If no application is specified then it will be applied for
all the other requests. Fields can be masked or filtered in the request messages received.
You can configure the masking criteria as required for the XPath, JSONPath, and Regex
expressions based on the content-type. This policy can also be applied at the API scope
level.
The table lists the content-type and masking criteria mapping.
Content-type Masking Criteria
application/xml XPath
text/xml
text/html
application/json JSONPath
application/json/
badgerfish
text/plain Regex
The table lists the masking criteria properties that you can configure to mask the data in
the request messages received:
Consumer Optional. Specifies the applications for which the masking

Applications criterion has to be applied.
Start typing the application name, select the application
from the type-ahead search results displayed, and click
to add one or more applications.
M
Even Header
Policies
For example: If there is a DataMasking(DM1) criteria

created for application1 a second DataMasking(DM2) for
application2 and a third DataMasking(DM3) with out any
application, then for a request that comes from consumer1
the masking criteria DM1 is applied, for a request that
comes from consumer2 DM2 is applied. If a request comes
with out any application or from any other application
except application1 and application2 DM3 is applied.

applications from the list.
XPath: Specifies the masking criteria for XPath expressions in the request
messages.
Masking Criteria Click Add masking criteria and provide the following
information and click Add:
Masking Type. Specifies the type of masking required.
You select either Mask or Filter. Selecting Mask replaces
the value with the given value (the default value being
********). Selecting Filter removes the field completely.
Query expression. Specify the query expression that has
to be masked or filtered.
For example: /pet/details/status, /user/details/card/
ccnumber.
Mask Value. This is available if masking type selected
is Mask. Provide a mask value. For example: sold, any
mask value #####.
Note: You can add multiple masking criteria.
Namespace. Specifies the following Namespace

information:
expression to be validated

by clicking .
M
Odd Header
Policies
JSONPath: This is applicable only for REST API. Specifies the masking criteria for
JSONPath expressions in the request messages.
Query expression. Specify the query expression
that has to be masked or filtered. For example:
$.pet.details.status
Mask Value. This is available if masking type selected is
Mask. Provide a mask value. For example: sold
Regex: Specifies the masking criteria for regular expressions in the request
messages.
to be masked or filtered. For example: [0-9]+
Mask. Provide a mask value. For example: ########
Apply for Select this option to apply masking criteria for transactional
transaction logs.
Logging
Apply for payload Select this option to apply masking criteria for payload in
the incoming request.
M
Even Header
Policies
Routing
The policies in this stage enforce routing of requests to target APIs based on the rules
you can define to route the requests and manage their respective redirections according
to the initial request path. The policies included in this stage are:
Content-based Routing
Context-based Routing
Dynamic Routing
Load Balancer Routing
Straight Through Routing
Custom HTTP Header
Outbound Authentication - Transport
Outbound Authentication - Message
JMS/AMQP Routing
JMS/AMQP Properties
In cases where the internal server is protected by a firewall, the endpoint in the
routing policy that is applied should be configured as apigateway://registrationPort-
aliasname /relative path of the API . Here the registration port alias name is the alias name
configured for the external registration port to communicate with the internal port.
Content-based Routing
If you have a native API that is hosted at two or more endpoints, you can use the
Content-based routing protocol to route specific types of messages to specific endpoints.
You can route messages to different endpoints based on specific values that appear in
the request message. You might use this capability, for example, to determine which
operation the consuming application has requested, and route requests for complex
operations to an endpoint on a fast machine. For example, if your entry protocol is HTTP
or HTTPS, you can select the Content-based routing. The requests are routed according
to the content-based routing rules you create. You may specify how to authenticate
requests.
Default Route To: Specifies the URLs of two or more native services in a pool to
which the requests are routed.
Endpoint URI Specifies the URI of the native API endpoint to route
the request to in case all routing rules evaluate to
M
Odd Header
Policies
False. Service registries that have been added to the
API Gateway instance are also included in the list.
If you choose a service registry, API Gateway sends
a request to the service registry to discover the
IP address and port at which the native service is
running. API Gateway replaces the service registry
alias in the Endpoint URI with the IP address and port
returned by the service registry.
For example, if your service is hosted at the URL:
http://host:port/abc/, you need to configure the
Endpoint URI as: http://${ServiceRegistryName}/
abc/.
HTTP Method This is applicable for REST-based APIs.

Specifies the available routing methods: GET, POST,
PUT, DELETE, and CUSTOM (default).
When CUSTOM is selected, the HTTP method in the
Note: Software AG recommends to use Request

Transformation > Method Transformation to achieve
this as other transformations can also be done
under the same policy.
SOAP Optimization This is applicable for SOAP-based APIs.

Method
Specifies the optimization methods that API Gateway
can use to parse SOAP requests to the native API.
Select one of the following options:
MTOM. API Gateway uses the Message Transmission
Optimization Mechanism (MTOM) to parse SOAP
requests to the API.
SwA. API Gateway uses the SOAP with Aachment
(SwA) technique to parse SOAP requests to the API.
None. API Gateway does not use any optimization
method to parse the SOAP requests to the API. This
is selected by default.
M
Even Header
Policies
HTTP Connection Specifies the time interval (in seconds) after which a
Timeout (seconds) connection aempt times out.
If a value 0 is specified (or if the value is not specified),
API Gateway uses the default value 30 seconds.
Read Timeout Specifies the time interval (in seconds) after which a
(seconds) socket read aempt times out.
Pass WS-Security This is applicable for SOAP-based APIs.

Headers
Selecting this indicates that API Gateway should pass
the WS-Security headers of the incoming requests to
the native API.
SSL Configuration. Specifies values to enable SSL client authentication that API
Gateway uses to authenticate incoming requests for the native API.
Keystore Alias Specifies the keystore alias of the instance of

Integration Server on which API Gateway is running.
This value (along with the value of Client Certificate
Alias) is used for performing SSL client authentication.
Key Alias Specifies the alias for the private key, which must be
stored in the keystore specified by the keystore alias.
Service Registry Configuration
Service Discovery Values required for constructing the discovery service

Endpoint Parameter URI.
Parameter: An alias that you have included in the
discovery service URI while adding the service
registry to API Gateway.
Value: A value for the path parameter. The alias
specified in Path Parameter is substituted with this
value when invoking the discovery service.
For example: if the service registry configuration of
the service registry that you have selected in Endpoint
URI has Service discovery path set to "/catalog/service/
{serviceName}" (and the {serviceName} alias is
intended for passing the service name), you must
M
Odd Header
Policies
enter {serviceName} as Parameter and the name of the
service as Value.
Rule: Defines the routing decisions based on one of the following routing options.
Click Add Rule and provide the following information.
Payload Identifier Specifies using the payload identifier to identify the

client, extract the custom authentication credentials
supplied in the request represented using the payload
identifier, and verify the client's identity.
Add.
Expression type. Specifies the type of expression,
which is used for identification. You can select one
the following expression type:
expression that the specified XPath expression
type in the request has to be converted to. For
example: /name/id

URI by clicking .
JSONPath. Provide the Payload Expression that

specifies the payload expression that the specified
JSONPath expression type in the request has to
be converted to. For example: $.name.id
Text. Provide the Payload Expression that specifies
the payload expression that the specified Text
expression type in the request has to be converted
to. For example: any valid regular expression.

allowed. For example, you can add a maximum of
M
Even Header
Policies
three payload identifiers, each being of a different
type.
Route To. Specifies the Endpoint URI of native APIs in a pool to which the
requests are routed.
the request to. You can use service registries in a
similar manner as described in the main Endpoint URI
above.

Soap Optimization This is applicable for SOAP-based APIs.

Method
M
Odd Header
Policies


Headers
the native API.
SSL Configuration Specifies values to enable SSL client authentication

that API Gateway uses to authenticate incoming
requests for the native API.
Keystore Alias. Specifies the keystore alias of the
instance of Integration Server on which API Gateway
is running. This value (along with the value of Client
Certificate Alias) is used for performing SSL client
authentication.
Key Alias. Specifies the alias for the private key,
which must be stored in the keystore specified by the
keystore alias.

service as Value.
M
Even Header
Policies
Context-based Routing
If you have a native API that is hosted at two or more endpoints, you can use the
Context-based protocol to route specific types of messages to specific endpoints.
The requests are routed according to the context-based routing rules you create. For
example, if your entry protocol is HTTP or HTTPS, you can select the Context-based
routing. A routing rule specifies where requests should be routed, and the criteria by
which they should be routed there. You may specify how to authenticate requests.
Default Route To. Specifies the URLs of two or more native services in a pool to
which the requests are routed.
abc/.
HTTP Method This is applicable to REST-based APIs.


M
Odd Header
Policies

Method
MTOM.API Gateway uses the Message Transmission
method to parse the SOAP requests to the API. This is
selected by default.


Headers
the native API.
M
Even Header
Policies

service as Value.
Rule. Defines the routing decisions based on one of the following routing options.
Name Provide a name for the rule.
Condition Operator Specifies the condition operator to be used.

Select one of the following operators:
OR. Specifies that one of the set conditions should be
applied.
AND. Specifies all the set conditions should be
applied.
Condition Specify the context variables for processing client

requests.
Variable Select any of the following variables:

Consumer. Specifies the name of the consumer
application in the text box.
Variable Value. Provide a value in the Variable
Value text box.
Date
M
Odd Header
Policies
Operator. Select an operator: After or Before .

Variable Value. Type a date value in the text box.
IPV4. Specifies that IP version to be IPV4.
From IP.Type an IP address range.
To IP. Type an IP address range.
IPV6. Specifies that IP version to be IPV4.
From IP. Type an IP address range.
To IP. Type an IP address range.
Predefined Context Variable
Predefined Context. Select a predefined context.
Operator. Select one of the following operators:
Equal To or Not Equal To.
Variable Value. Type a value for the selected
predefined context.
Custom Context Variable
Variable Name. Type a name for the
custom context variable. Use the
pub.apigateway.ctxvar:setContextVariable API
for seing the value for the custom context
variable. All custom-defined context variables
must be declared in a custom namespace that is
identified by using the prefix mx (for example,
mx:CUSTOM_VARIABLE). All parameter names
are case-sensitive. For more information on
pub.apigateway.ctxvar:setContextVariable service, see
“The API for Context Variables” on page 339.
Data Type. Select the data type: String or Integer.
Operator. Select one of the following operators
based on the Data Type selected:
String: Equal To or Not Equal To
Integer: Equal To, Not Equal To, Greater Than, or
Less Than
Variable Value. Type a value for the selected custom
context.
Time
M
Even Header
Policies
Operator. Select an operator: After or Before.

Hours. Type a time value in hours.
Minutes. Type a time value in minutes.
Route To. Specifies the endpoint URI of native services in a pool to which the
the request to. You can use service registries in a
similar manner as described in the main Endpoint URI
above.


Method
Specifies values to enable SSL authentication for SOAP
APIs.
method to parse the SOAP requests to the API. This is
selected by default.
M
Odd Header
Policies
(seconds) socket read aempt timesout.

Headers
the native API.
SSL Configuration Specifies values to enable SSL client authentication

that API Gateway uses to authenticate incoming
requests for the native API.
instance of Integration Server on which API Gateway
is running. This value (along with the value of Client
authentication
keystore alias.

service as Value.
M
Even Header
Policies
Dynamic Routing
This policy enables API Gateway to support dynamic routing of virtual aliases based on
policy configuration. The configured policies are enforced on the request sent to an API
and these requests are forwarded to the dynamic endpoint based on specific criteria that
you specify.
Route To. Specifies the URLs of two or more native services in a pool to which the
abc/.



Method
M
Odd Header
Policies


Headers
the native API.

M
Even Header
Policies

service as Value.
Rule. Defines the routing decisions based on one of the following routing options.
Route Using Defines the dynamic URL based on the HTTP header
value sent by the client or the context variable value.
Header: Select and specify the Name required. This
header name is configured by the API provider and
is used to decide the routing decisions at the API
level. The request message must be routed to the
dynamic URL generated from the HTTP header
value.
Context: The API providers must provide IS service
in the policy, Invoke webMethods Integration Server.
IS service would perform custom manipulations
and set the value for the Context Variable
ROUTING_ENDPOINT. API Gateway takes this
ROUTING_ENDPOINT value as the native endpoint
value and performs the routing.
Route To Specifies the endpoint URI of native services in a pool

to which the requests are routed.
Endpoint URI . Specifies the URI of the native API
endpoint to route the request to. You can use service
M
Odd Header
Policies
registries in a similar manner as described in the
main Endpoint URI above.
HTTP Method. This applicable to REST-based APIs.
HTTP Connection Timeout (seconds). Specifies the time
interval (in seconds) after which a connection aempt
times out.
Read Timeout (seconds). Specifies the time interval (in
seconds) after which a socket read aempt times out.
SSL Configuration. Specifies values to enable SSL client
authentication that API Gateway uses to authenticate
incoming requests for the native API. Provide the
instance of Integration Server on which API
Gateway is running. This value (along with
the value of Client Certificate Alias) is used for
performing SSL client authentication
which must be stored in the keystore specified by
the keystore alias.

Method
M
Even Header
Policies

Headers
the native API.
Load Balancer Routing

If you have an API that is hosted at two or more endpoints, you can use the load
balancing option to distribute requests among the endpoints. Requests are distributed
across multiple endpoints. The requests are routed based on the round-robin execution
strategy. The load for a service is balanced by directing requests to two or more services
in a pool, until the optimum level is achieved. The application routes requests to services
in the pool sequentially, starting from the first to the last service without considering the
individual performance of the services. After the requests have been forwarded to all the
services in the pool, the first service is chosen for the next loop of forwarding.
If the entry protocol is HTTP or HTTPS, you can select the Load Balancer routing.
Route To. Specifies the URLs of two or more native services in a pool to which the
For example, if your service is hosted at the
URL: http://host:port/abc/, you need
to configure the Endpoint URI as: http://
${ServiceRegistryName}/abc/.
HTTP Method This is applicable to REST APIs.

M
Odd Header
Policies


Method
Read Timeout (seconds) Specifies the time interval (in seconds) after which a
socket read aempt times out.
Suspend duration A numeric timeout value (in seconds). The default

(seconds) value is 30.
This property specifies the time, in seconds, for which
API Gateway temporarily suspends an endpoint,
whenever Read time-out or Connection time-out
occurs for the endpoint, and routes the request to the
next configured endpoint in this time interval.
For example: If you have 3 endpoints configured
endpoint #1, endpoint #2, and endpoint #3, the
suspend duration is configured as 60 seconds
for endpoint #2, and there is a Read Timeout or
Connection Timeout for endpoint #2, then API
M
Even Header
Policies
Gateway temporarily suspends endpoint #2 for
60 seconds. In this time interval API Gateway
skips endpoint #2 while routing the requests to the
configured endpoints.
Request 1 -> endpoint #1
Request 2 -> endpoint #3 (endpoint #2 is suspended
for 60 seconds and hence the request is sent to
endpoint #3
Request 3 -> endpoint #1

Headers
the native API.

This value (along with the value of Client
authentication.
stored in the keystore specified by the above keystore
alias.

M
Odd Header
Policies
service as Value.
Straight Through Routing

When you select the Straight Through routing protocol, the API routes the requests
directly to the native service endpoint you specify. If your entry protocol is HTTP or
HTTPS, you can select the Straight Through routing policy.
Parameter Value
abc/.


M
Even Header
Policies
Parameter Value

Method

Headers
the native API.
SSL configuration - Specifies values to enable SSL client authentication that API

M
Odd Header
Policies
Parameter Value

service as Value.
Custom HTTP Header

You can use this policy to route requests based on the custom HTTP headers specified
for the outgoing message to the native service.
HTTP Header Key Specifies the HTTP header key contained in the
requests.
Header Value Specifies the Header value contained in the requests.
You can add multiple entries for the Header key-value pair by clicking .
Outbound Authentication - Transport

When the native API is protected and expects the authentication credentials to be passed
through transport headers, you can use this policy to provide the credentials that will be
added to the request and sent to the native API. API Gateway supports a wide range of
authentication schemes, such as Basic Authentication, Kerberos, NTLM, and OAuth, at
the transport-level.
M
Even Header
Policies
Note: Transport-level authentication can be used to secure inbound communication

of both the SOAP APIs and the REST APIs.
Authentication scheme Select one of the following schemes for outbound

authentication at the transport level:
Basic. Uses basic HTTP authentication details to
Kerberos. Uses Kerberos credentials for
authentication.
NTLM. Uses NTLM configuration for authentication.
OAuth2. Uses OAuth token details to authenticate the
client.
JWT. Uses JSON web token details to authenticate the
client.
Anonymous. Authenticates the client without any
credentials.
Alias. Uses the configured alias name for
authentication.
Authenticate using Select one of the following modes to authenticate the

client:
Custom credentials. Uses the values specified in the
policy to obtain the required token to access the
native API.
Delegate incoming credentials. Uses the values specified
in the policy by the API providers to select whether
to delegate the incoming token or act as a normal
client.
Incoming HTTP Basic Auth credentials. Uses the
incoming user credentials to retrieve the
authentication token to access the native API.
Incoming kerberos credentials. Uses the incoming
kerberos credentials to access the native API.
Incoming OAuth token. Uses the incoming OAuth2
token to access the native API.
M
Odd Header
Policies
Incoming JWT. Uses the incoming JSON Web Token

(JWT) to access the native API.
Transparent. Enables NTLM handshake between
client and native API. API Gateway does not perform
any authentication before passing the incoming
requests to native API. It simply passes the incoming
credentials to native API. The NTLM authentication
happens at the native API.
Basic Uses the HTTP authentication details to authenticate

the client.
API Gateway supports the following modes of HTTP
authentication:
Custom credentials
Incoming HTTP Basic Auth credentials
Provide the following credentials:
User Name. Specifies the user name.
Password. Specifies the password of the user.
Domain Name. Specifies the domain in which the user
resides.
Kerberos Uses the Kerberos credentials to authenticate the

client.
API Gateway supports the following modes of
Kerberos authentication:
Custom credentials
Delegate incoming credentials
Incoming HTTP basic auth credentials
Incoming kerberos credentials
Client principal. Provide a valid client LDAP user
name.
Client password. Provide a valid password of the client
LDAP user.
M
Even Header
Policies
Service principal. Provide a valid SPN. The specified

value is used by the client to obtain a service ticket
from the KDC server.
Service Principal Name Form. The SPN type to use while
authenticating an incoming client principal name.
User name. Specifies the username form.
Hostbased. Specifies the host form.
NTLM Uses the NTLM credentials to authenticate the client.

API Gateway supports the following modes of NTLM
authentication:
Custom credentials
Incoming HTTP basic auth credentials
Transparent
Domain Name. Specifies the domain in which the user
resides.
OAuth2 Uses the OAuth2 token to authenticate the client.

API Gateway supports the following modes of NTLM
authentication:
Custom credentials
Incoming OAuth token
OAuth2 token. Specifies the client's OAuth2 token.
JWT Uses the JSON Web Token (JWT) to authenticate the

client.
If the native API is enforced to use JWT for
authenticating the client, then API Gateway enforces
the need for a valid JWT in the outbound request
while accessing the native API.
M
Odd Header
Policies
API Gateway supports the Incoming JWT mode of JWT

authentication.
Alias Name of the configured alias.
Outbound Authentication - Message

When the native API is protected and expects the authentication credentials to be passed
through payload message, you can use this policy to provide the credentials that is
added to the request and sent to the native API. API Gateway supports a wide range of
authentication schemes, such as WSS Username, SAML, and Kerberos, in addition to
signing and encryption at the message-level.
Note: Message-level authentication can be used to secure outbound communication

of only SOAP APIs.
Authentication scheme Select one of the following schemes for outbound

authentication at the message level:
WSS username. Uses WSS credentials authenticate the
client.
SAML. Uses SAML issuer configuration details for
authentication.
Kerberos. Uses Kerberos credentials for
authentication.
None. Authenticates the client without any
authentication schemes.
Alias. Uses the configured alias name for
authentication.
Remove WSS headers. Uses the WSS headers for
authentication.
Authenticate using Select one of the following modes to authenticate the

client:
Custom credentials. Uses the values specified in the
policy to obtain the required token to access the
native service.
M
Even Header
Policies
Incoming HTTP Basic Auth credentials. Uses the

incoming user credentials to retrieve the
authentication token to access the native API
Delegate incoming credentials. Uses the values specified
in the policy by the API providers to select whether
to delegate the incoming token or act as a normal
client.
WSS username Uses the WSS credentials to authenticate the client.

Kerberos Uses the Kerberos credentials to authenticate the

client.
Client principal. Provide a valid client LDAP user
name.
Client password. Provide a valid password of the client
LDAP user.
Service principal. Provide a valid SPN. The specified
value is used by the client to obtain a service ticket
from the KDC server.
Service Principal Name Form. The SPN type to use while
authenticating an incoming client principal name.
User name. Specifies the username form.
Hostbased. Specifies the host form.
SAML Provide the SAML issuer that is configured.
Signing and Encryption Uses the signing and encryption configuration details
Configurations to authenticate the client.
Keystore Alias. Specifies a user-specified text identifier
for an API Gateway keystore. The alias points to
M
Odd Header
Policies
a repository of private keys and their associated
certificates.
keystore alias.
Truststore alias. Specifies the alias for the truststore.
The truststore contains the trusted root certificate
for the CA that signed the API Gateway certificate
associated with the key alias.
Certificate alias. Provide a text identifier for the
certificate associated with the truststore alias. API
Gateway populates the certificate alias list with the
certificate aliases from the selected truststore alias.
Alias Uses the Kerberos credentials to authenticate the

client. Provide the name of the configured alias.
Traffic Monitoring
The policies in this stage provide ways to enable logging request and response payload,
enable monitoring run-time performance conditions for APIs and applications, enforce
limits for the number of service invocations during a specified time interval and send
alerts to a specified destination when the performance conditions are violated, and
enable caching of the results of API invocations depending on the caching criteria
defined. The policies included in this stage are:
Log Invocation
Monitor Service Performance
Monitor Service Level Agreement
Service Result Cache
Log Invocation
This policy enables logging requests or responses to a specified destination. This action
also logs other information about the requests or responses, such as the API name,
operation name, the Integration Server user, a timestamp, and the response time.
In addition the Store Request and Store Response options when selected store the
following:
requestHeaders
M
Even Header
Policies
responseHeaders
queryParameters in case of a REST request
corelationId - an id that can be used to query the log
customFieldList - custom fields specified for a transaction event
errorOrigin - specifies where the error originated from, native service or API
Gateway.
To add a custom field you have to implement a flow service adhering to
pub.apigateway.utils:customFieldInTransactionEventSpec specification and call the flow
service using Invoke webMethods IS policy in the stage you want to add the custom
field to the transaction event. The custom field's key and value should be of String type.
Note: Sensitive information like Authorization headers present in request headers,

response headers, and query parameters are masked to "**************"
Store Request Logs all requests.
Store Response Logs all responses.
Compress Payload Data Compresses the logged payload data.
Log Generation Specifies how frequently to log the payload.

Frequency
Always. Logs all requests and responses.
On Failure. Logs only the failed requests and
responses.
On Success. Logs only the successful responses and
requests.
Destination Specifies the destination where to log the payload.

Select the required options:
API Gateway
API Portal
CentraSite
M
Odd Header
Policies
Note: This option is applicable only for the APIs

published from CentraSite to API Gateway.
Digital Events
Elasticsearch
Email (you can add multiple email addresses by
clicking ).
Note: If an email alias is available, you can type

the email alias in the Email Address field with
the following syntax, ${emailaliasname}. For
example, if test is the email alias, then type
${test}.
Local Log: You can select the severity of the messages

to be logged (logging level) from the Log Level drop-
down list. The available log levels are ERROR, INFO,
and WARN.
Note: Set the Integration Server Administrator's

logging level for API Gateway to match
the logging levels specified for the run-
time actions (go to Settings > Logging
> Server Logger). For example, if a Log
Invocation action is set to the logging level
of Error, you must also set Integration
Server Administrator's logging level
for API Gateway to Error. If the action's
logging level is set to a low level (Warning-
level or Information level), but Integration
Server Administrator's logging level for
API Gateway is set to a higher level (Error-
level), then only the higher-level messages
are wrien to the log file.
Entries posted to the local log are
identified by a product code of YAI and
suffixed with the initial alphabet of the
logging level selected. For example,
for an error level, the entry appears as
[YAI.0900.0002E].
M
Even Header
Policies
Monitor Service Performance

This policy is similar to the Monitor Service Level Agreement policy and does monitor
the same set of run-time performance conditions for an API, and sends alerts when
the performance conditions are violated. However, this policy monitors run-time
performance at the API level. Parameters like success count, fault count and total request
count are immediate monitoring parameters and the evaluation happens immediately
after the limit is breached. The rest of the parameters are Aggregated monitoring
parameters whose evaluation happens once the configured interval is over. If there is
a breach in any of the parameters, an event notification ( Monitor event) is sent to the
configured destination. In a single policy, multiple action configurations behave as AND
condition. The OR condition can be achieved by configuring multiple policies.
Parameter Value
Action Configuration. Specifies the type of action to be configured.
Name Specifies the name of the metric to be monitored.

You can select one of the available metrics:
Availability. Indicates whether the API was available to
the specified clients in the current interval.
Average Response Time. Indicates the average time taken
by the service to complete all invocations in the current
interval. The average is calculated from the instant the
API activation takes place for the configured interval.
For example, if you set an alert for Average response
time greater than 30 ms with an interval of 1 minute
then on API activation, the monitoring interval starts
and the average of the response time of all runtime
invocations for this API in 1 minute is calculated. If this
is greater than 30 ms, then a monitor event is generated.
If this is configured under Monitor service performance,
then all the runtime invokes are taken into account.
Fault Count. Indicates the number of faults returned in
the current interval.
Maximum Response Time. Indicates the maximum time to
respond to a request in the current interval.
Minimum Response Time. Indicates the minimum time to
Success Count. Indicates the number of successful
requests in the current interval.
M
Odd Header
Policies
Parameter Value
Total Request Count. Indicates the total number of

requests (successful and unsuccessful) in the current
interval.
Operator Specifies the operator applicable to the metric selected.

Select one of the available operator: Greater Than, Less
Than, Equals To.
Value Specifies the alert value for which the monitoring is

applied.
Destination Specifies the destination where the alert is to be logged.

API Gateway
API Portal
CentraSite

Elasticsearch
Email (you can add multiple email addresses by clicking
).

${test}.

and WARN.

M
Even Header
Policies
Parameter Value
Server Administrator's logging level for API
Gateway to Error. If the action's logging
level is set to a low level (Warning-level or
Information level), but Integration Server
Administrator's logging level for API
Gateway is set to a higher level (Error-level),
then only the higher-level messages are
wrien to the log file.
Entries posted to the local log are identified
by a product code of YAI and suffixed with
the initial alphabet of the logging level
selected. For example, for an error level, the
entry appears as [YAI.0900.0002E].
Alert Interval Specifies the time period in which to monitor

performance before sending an alert if a condition is
violated.
The timer starts once the API is activated and resets after
the configured time interval. If and API is deactivated the
interval gets reset and on API activation its starts afresh.
Unit Specifies the unit for the time interval in minutes, hours,
days, or weeks for the alert interval.
Alert Frequency Specifies how frequently to issue alerts for the counter-
based metrics (Total Request Count, Success Count, Fault
Count).
Select one of the options:
Only Once. Triggers an alert only the first time one of the
specified conditions is violated.
Every Time. Triggers an alert every time one of the
Alert Message Specifies the text to be included in the alert.
Monitor Service Level Agreement

This policy monitors a set of run-time performance conditions for an API, and sends
alerts to a specified destination when the performance conditions are violated.
This policy enables you to monitor run-time performance for one or more specified
applications. You can configure this policy to define a Service Level Agreement (SLA),
which is a set of conditions that defines the level of performance that an application
M
Odd Header
Policies
should expect from an API. You can use this policy to identify whether the API
threshold rules are met or exceeded. For example, you might define an agreement
with a particular application that sends an alert to the application if responses are not
sent within a certain maximum response time. You can configure SLAs for each API or
application combination.
Parameters like success count, fault count and total request count are immediate
monitoring parameters and the evaluation happens immediately after the limit is
breached. The rest of the parameters are Aggregated monitoring parameters whose
evaluation happens once the configured interval is over. If there is a breach in any of the
parameters, an event notification ( Monitor event) is sent to the configured destination.
In a single policy, multiple action configurations behave as AND condition. The OR
condition can be achieved by configuring multiple policies.
Parameter Value
Action Configuration. Specifies the type of action to be configured.
Name Specifies the name of the metric to be monitored.

You can select one of the available metrics:
Availability. Indicates whether the API was available to the
specified clients in the current interval
Average Response Time. Indicates the average time taken
by the service to complete all invocations in the current
interval. The average is calculated from the instant the
API activation takes place for the configured interval.
For example, if you set an alert for Average response
time greater than 30 ms with an interval of 1 minute then
on API activation, the monitoring interval starts and the
average of the response time of all runtime invocations
for this API in 1 minute is calculated. If this is greater
than 30 ms, then a monitor event is generated. If this
is configured under Monitor service level agreement
policy with an option to configure applications so that
application specific SLA monitoring can be done, then
the monitoring for the average response time is done
only for the specified application.
Fault Count. Indicates the number of faults returned in the
current interval.
Maximum Response Time. Indicates the maximum time to
Minimum Response Time. Indicates the minimum time to
M
Even Header
Policies
Parameter Value
Success Count. Indicates the number of successful

requests in the current interval.
Total Request Count. Indicates the total number of requests
(successful and unsuccessful) in the current interval.
Operator Specifies the operator applicable to the metric selected.

Select one of the available operator: Greater Than, Less Than,
Equals To.
Value Specifies the alert value for which the monitoring is

applied.
Destination Specifies the destination where the alert is to be logged.

API Gateway
API Portal
CentraSite

Elasticsearch
Email (you can add multiple email addresses by clicking
).
Note: If an email alias is available, you can type the

email alias in the Email Address field with the
following syntax, ${emailaliasname}. For example,
if test is the email alias, then type ${test}.

down list. The available log levels are ERROR, INFO, and
WARN.

logging level for API Gateway to match the
logging levels specified for the run-time
actions (go to Settings > Logging > Server
Logger). For example, if a Log Invocation
action is set to the logging level of Error,
you must also set Integration Server
M
Odd Header
Policies
Parameter Value
Administrator's logging level for API Gateway
to Error. If the action's logging level is set to
a low level (Warning-level or Information
level), but Integration Server Administrator's
logging level for API Gateway is set to a
higher level (Error-level), then only the higher-
level messages are wrien to the log file.
Entries posted to the local log are identified by
a product code of YAI and suffixed with the
initial alphabet of the logging level selected.
For example, for an error level, the entry
appears as [YAI.0900.0002E].
Alert Interval Specifies the time period (in minutes) in which to monitor
performance before sending an alert if a condition is
violated.
The timer starts once the API is activated and resets after
the configured time interval. If and API is deactivated the
interval gets reset and on API activation its starts afresh.
Alert Frequency Specifies how frequently to issue alerts for the counter-
based metrics (Total Request Count, Success Count, Fault
Count).
Select one of the options:
Only Once. Triggers an alert only the first time one of the
Every Time. Triggers an alert every time one of the
Alert Message Specifies the text to be included in the alert.
Consumer Specifies the application to which this Service Level

Applications Agreement applies.
You can type a search term to match an application and
click to add it.
You can add multiple applications or delete an added
application by clicking .
M
Even Header
Policies
Throttling Traffic Optimization

This policy limits the number of service invocations during a specified time interval,
and sends alerts to a specified destination when the performance conditions are
violated. You can use this action to avoid overloading the back-end services and their
infrastructure, to limit specific clients in terms of resource usage, and so on.
Limit Configuration.
Rule name Specifies the name of throling rule to be applied. For

example, Total Request Count.
Operator Specifies the operator that connects the rule to the value
specified.
Select one of the operators: Greater Than, Less Than,
Equals To.
Value Specifies the value of the request count beyond which

the policy is violated.
Destination Specifies the destination to log the alerts.

API Gateway
API Portal
CentraSite

Elasticsearch
Email (you can add multiple email addresses by
clicking ).

${test}.
M
Odd Header
Policies

and WARN.

Server Administrator's logging level for API
Gateway to Error. If the action's logging
level is set to a low level (Warning-level or
Information level), but Integration Server
Administrator's logging level for API
Gateway is set to a higher level (Error-level),
then only the higher-level messages are
wrien to the log file.
Entries posted to the local log are identified
by a product code of YAI and suffixed with
the initial alphabet of the logging level
selected. For example, for an error level, the
entry appears as [YAI.0900.0002E].
Alert Interval Specifies the interval of time for the limit to be reached.
Unit Specifies the unit for the time interval in minutes, hours,
days, or weeks for the alert interval.
Alert Frequency Specifies the frequency at which the alerts are issued.
Specify one of the options:
Only Once. Triggers an alert only the first time the
specified condition is violated.
Every Time. Triggers an alert every time the specified
condition is violated.
Alert Message Specifies the text message to be included in the alert.
Consumer Specifies the application to which this policy applies.

Applications
M
Even Header
Policies
You can type a search term to match an application and

click to add it.
You can add multiple applications or delete an added
application by clicking .
Service Result Cache

This policy enables caching of the results of API invocations depending on the caching
criteria defined. You can define the elements for which the API responses are to be
cached based on the criteria such as HTTP Header, XPath, Query parameters, and so
on. You can also limit the values to store in the cache using a whitelist. For the elements
that are stored in the cache, you can specify other parameters such as Time to Live and
Maximum Response Payload Size.
Caching the results of an API request increases the throughput of the API call and
improves the scalability of the API.
The cache criteria applicable for a SOAP-based API request are HTTP Header and
XPATH. The cache criteria applicable for a REST-based API request are HTTP Header
and Query parameters.
Note: If there are no values set for any of the criteria, then, by default, all the SOAP
requests and GET requests for the Rest API are based on the URL.
Cache Criteria. Specifies the criteria that API Gateway uses to determine the
request component, that is, the actual payload based on which the results of the
API invocation are cached.
HTTP Header Uses the HTTP header in the API request. You can use
this criterion for APIs that accept payloads only in HTTP
format.
Header Name. Specifies the HTTP header name.
Cache responses only for these values. API Gateway caches
the API responses only for requests whose cache criteria
match with those set for the action, and whose criteria
evaluation results in any one of the values in this list. You
can add multiple entries by clicking .
M
Odd Header
Policies
Note: If this field is empty, all the values that satisfy the
criterion are cached.
Query Parameters You can use this criterion for REST-based API requests.
Specifies the names and values of the query parameters to
filter the incoming requests and cache the results based on
the names and values specified.
Parameter Name. Specifies the parameter name.
Cache responses only for these values. API Gateway
caches the API responses only for requests whose cache
criteria match those set for the action, and whose criteria
XPath You can use this criterion for SOAP-based API requests
whose payload is a SOAP envelope. Uses the XPath
expression in the API request.
Name Space. Specifies the namespace of the XPath
expression.
Prefix. Specifies the prefix for the namespace.
URI. Specifies the namespace URI.
XPath Expression. Specifies the XPath expression in the API

request.
Cache responses only for these values. API Gateway
caches the API responses only for requests whose cache
criteria match those set for the action, and whose criteria
Note: If this field is empty, all the values that satisfy the
criteria are cached.
Time to Live (e.g., Specifies the lifespan of the elements in the cache after
5d 4h 1m) which the elements are considered to be out-of-date.
The time is specified in terms of days, hours, and minutes;
for example, 5d 4h 1m.
M
Even Header
Policies
The default time format is minutes if the input is a

number.
Maximum Specifies the maximum payload size for the API in kilo
Response Payload bytes.
Size (in KB,
The value -1 stands for unlimited payload size.
-1=unlimited)
Example of enforcing caching criteria:
Cache HTTP Header Query XPATH Values

criteria parameters
C1 Header1 h1, h2
C2 Header2
C3 query1 q1, q2
In the example, there are two HTTP headers and one query parameter as cache criteria.
The HTTP Header Header2 has no values specified. Hence, all the incoming requests
with the HTTP Header Header2 are cached.
When there are multiple cache criteria, the following behaviour is observed in the cache
result:
If the incoming request R1 matches criteria C1, then the result is cached. API
Gateway responds to any further incoming request R1 that matches criteria C1 from
the cache.
If the incoming request R1 matches criteria C1 and C2, then the result is cached as a
new request.
If you configure multiple cache criteria, and if one or more cache criteria match, then
the result is cached. The criteria are matched with the cached results while caching
the request, and it follows the AND condition among the matched criteria.
Response Processing
These policies are used to specify how the response message from the API has to be
transformed or pre-processed and configure the masking criteria for the data to be
masked before it is submied to the application. This is required to protect the data
and accommodate differences between the message content that an API is capable of
submiing and the message content that an application expects. The policies included in
this stage are:
M
Odd Header
Policies
CORS
Data Masking
This policy processes the native API’s response messages into the format required by the
application, before API Gateway returns the responses to the application.
If Comply to IS Spec parameter is configured as true, API
Gateway invokes the IS Service with IS specification in the path
pub.apigateway.invokeISService.specifications:ResponseSpec (for Response Processing)
The following are the input and output parameters for REST and SOAP APIs as
specified in the above IS Specification.
API Input parameters Output parameters

type
REST headers headers

payload payload
statusCode statusCode
statusMessage statusMessage
apiName
requestUrl
correlationID
(this is unique
for request and
response)
SOAP headers headers

payload payload
statusCode statusCode
statusMessage statusMessage
apiName
M
Even Header
Policies
API Input parameters Output parameters

type
payloadObject
requestUrl
correlationID
(this is unique
for request and
response)
Note: For SOAP to REST APIS:

For SOAP to REST APIS, the payload contains the transformed JSON
response.
In the 10.2 release, payload transformation does not happen automatically
for content-type transformation. When you change the content type,
ensure to do payload transformation also as part of IS Service.
Only Method Transformation happens when configured, but you have
to take care of adding payload during transformations involving method
When Comply to IS spec is true, you can change the values of headers,
query, payload, and so on, programatically using Message Context, as
well as using the pipeline variables given. Software AG recommends you
do not change those values directly in Message Context, as the values
in output pipeline variables are wrien to Message Context after the
invocation of IS Service.
If Comply to IS Spec parameter is set to false, API Gateway invokes the IS Service
with the same input and output parameters supported in 10.1 and the earlier versions::
proxy.name
JSONRESTContentString (REST only)
SOAPEnvelope (SOAP only)
EnvelopeString (SOAP only)
Invoke webMethods Integration Server Service
Add invoke Specifies the webMethods IS service to be invoked to

webMethods process the response messages and the authentication
mode for the IS service.
M
Odd Header
Policies
Integration Server
service
webMethods IS Service. Specify the webMethods IS
service to be invoked to pre-process the response
pre-process or post-process the response message.
want API Gateway to invoke the IS service.
Note: It is the responsibility of the user who activates

the API to review the value configured in Run as
User field to avoid misuse of this configuration.

Note: Software AG recommends users to configure the

policy with Comply to IS Spec as true, as you
can read or change the values of headers, and so
on, without having to read from or write to the
message context.
webMethods IS Specifies the webMethods IS service alias used to invoke

Service alias the webMethods IS service to pre-process the response
messages.
Start typing the webMethods alias name, select the alias
from the type-ahead search results displayed and click
to add one or more aliases.

aliases from the list.
This policy specifies the properties required to transform response messages from native
APIs into a format required by the client.
M
Even Header
Policies
This policy enables you to configure several transformations on the response messages
before it is sent to the client.
API Gateway supports the following parameter types that can be used to configure the
response.payload
response.headers
response.statusCode
response.statusMessage
API Gateway supports the following Query types that can be used to configure the
xpath
jsonPath
regex
When you use these syntaxes to extract a value from the payload, the content-types
applicable are:
${payload.jsonPath} - application/json, application/json/badgerfish
${payload.regex} - text/plain
${payload.xpath} - application/xml, text/xml, text/html.
Condition Conditions are used to specify when the policy has to be

executed. We can add multiple conditions with logical
operators.
AND. API Gateway transforms the responses that comply
with all the configured conditions
OR. This is selected by default. API Gateway transforms
the responses that comply at least one configured
condition.
Click Add Condition and provide the following information
and click .
Variable. Specifies the variable type with a syntax as

follows:
M
Odd Header
Policies

string type - payload, statusCode and statusMessage.
For example: ${response.payload}
${PARAMTYPE.paramName} : This is applicable
for map types - headers. For example: ,
${response.header.Content-Type},
syntax is applicable for payload. XPath, JSONPath and
regex can be applied on payload. For example:
${response.payload.xpath[//ns:emp/
application/xml
json
${response.payload.regex[[0-9]+]} where
[0-9]+ is the regex to be applied on the payload if
contentType is text/plain
For example:
${response.payload.xpath[//
response.payload.jsonPath[$.cardDetails.number]}
response.payload.jsonPath[$.cardDetails.number]
|| response.payload.regex[[0-9]+]} This applies
Operator. Specifies the operator to use to relate variable
and the value provided. You can select one of the
following:
M
Even Header
Policies
Equals
Equals ignore case
Not equals
Contains
Exists
Transformation Configuration. Specifies various transformations to be configured.
Header/ Specifies the Header, Query or path transformation to be

Query/Path configured for the responses received from the native API.
Transformation
You can add or modify header, query or path
for REST API
transformation parameters by providing the following
and information:
Header Variable. Specifies the variable type with a syntax as
Transformation follows:
for SOAP API
string type - payload, statusCode and statusMessage.
For example: ${response.payload}
${PARAMTYPE.paramName} : This is applicable
for map types - headers. For example: ,
${response.header.Content-Type},
syntax is applicable for payload. XPath, JSONPath and
regex can be applied on payload. For example:
${response.payload.xpath[//ns:emp/
application/xml
M
Odd Header
Policies
json
${response.payload.regex[[0-9]+]} where
[0-9]+ is the regex to be applied on the payload if
contentType is text/plain
For example:
response.payload.jsonPath[$.cardDetails.number]}
response.payload.jsonPath[$.cardDetails.number]
|| response.payload.regex[[0-9]+]} This applies
You can add multiple variables and corresponding values

by clicking .
You can remove any header, query or path transformation

parameters by typing the value in the text box.
Note: In the 10.2 release, payload transformation does not

happen automatically for content-type transformation.
When you change the content type, ensure to do
payload transformation also as part of IS Service. For
example, if you change the content-type header from
application/xml to application/json using IS service,
M
Even Header
Policies
you must also change the respective payload from
application/xml to application/json
Status Specifies the status transformation to be configured for the

transformation responses received from the native API.
Code. Specifies the status code that is sent in the response
to the client.
Message. Specifies the Status message that is sent in the
response to the client.
Payload Specifies the payload transformation to be configured for

Transformation the responses received from the native API.
Click + Add xslt document to add an xslt document and
XSLT file. Specifies the XSLT file used to transform the
response messages as required.
Click Browse to browse and select a file.
Feature value. Specifies the value of the XSLT feature.
You can add more XSLT features and xslt documents
by clicking .
Click + Add xslt transformation alias and provide the

XSLT Transformation alias. Specifies the XSLT
transformation alias
Advanced Specifies the advanced transformation to be configured for

Transformation the responses received from the native API..
webMethods IS Service. Specify the webMethods IS service
to be invoked to process the response messages. The list
displays only the pre-shipped Integration Server services,
which you can invoke to pre-process or post-process the
request or response message.
M
Odd Header
Policies
You can add multiple services by clicking .
Run as User. Specifies the authentication mode to invoke

the IS service. If this field is left blank the incoming
credentials of the user, identified by API Gateway, are
used to authenticate and invoke the IS service. You can
also specify a particular user, you want API Gateway to
use to run the IS service.
Comply to IS Spec. Mark this as true if you want the input
and the output parameters to comply to the IS Spec
present in pub.apigateway.invokeISService.specifications
folder in wmAPIGateway package.
webMethods IS Service alias. Specifies the webMethods IS
service alias to be invoked to pre-process the request
messages.
Transformation Metadata. Specifies the metadata for transformation of the

responses received from the native API. For example, the namespaces
configured in this section can be used when you provide the syntax for XPath
${response.payload.xpath} For example: ${response.payload.xpath[//ns:emp/
ns:empName]}
Namespace Specifies the namespace information to be configured for

transformation.

by clicking .
Validate API Specification

This policy validates the responses against API's various specifications such as schema,
content-types, and HTTP Headers referenced in their corresponding formats as follows:
The schema is available as part of the API definition. The schema for SOAP API are
imported through WSDL and for REST APIs it can be through swagger, RAML or
can be uploaded by the user.
M
Even Header
Policies
The content- types are available as part of the API definition. FOR SOAP APIs these
are imported through WSDL and for REST APIs it can be through swagger, RAML
or can be uploaded by the user.
The HTTP Headers are specified in the Validate API Specification policy page
The response sent to the API by an application must conform with the structure or
format expected by the API. The responses from the native API are validated against the
API specifications in this policy to conform to the structure or format expected by the
API.
Various API specifications validated are:
Schema:
The responses from the native API are validated against the schema provided in the
API definition. The schema defines the elements and aributes and specifies the data
types of these elements to ensure that only appropriate data is allowed through to
the API.
For a REST API, the schema can be added inline or uploaded in the Technical
Information section on the API Details page. The validation depends on the Content-
type header in the request or Accept header in the response and the corresponding
schema validation would be executed. The default Content type/Accept header and
schema validation type mapping is as follows:
Content-type/Accept Schema validation type
application/json JSON schema

application/json/
badgerfish
application/xml XML schema

text/xml
text/html
text/plain Regex schema
For a SOAP API, the WSDL and the referenced schema must be provided in a zip
format. The JSON schema validation is supported for the operations that are exposed
as REST.
Content-types:
The responses from the native API are validated against the content-types specified
in the API definition.
HTTP Headers:
M
Odd Header
Policies
The responses from the native API are validated against the HTTP Headers specified
in this policy to conform to the HTTP headers expected by the API.
The run-time invocations that fail the specification validation are considered as
policy violations. Such policy violation events that are generated can be viewed in the
dashboard.
The table lists the API specification properties, you can specify for this policy, to be
validated:
Schema Validates the response payload against the appropriate

schema (based on the Content-type header in request or
Accept header in response).
Provide the following additional features for XML schema
validation:
Feature name. Specifies the name for the schema
configuration.
For example: TOLERATE_DUPLICATES,
NAMESPACE_GROWTH
Feature value. Specifies whether the feature value is True or
False.
Content-types Validates the content-types in the incoming response

against the content-types defined in that response's API
Specification. The configuration is provided in the API
details page.
HTTP Headers Validates the HTTP header parameters in the incoming

response against the HTTP headers defined in that
response's API Specification. The configuration is provided
Condition: Specifies the logical operator to use to validate
multiple HTTP headers in the incoming API responses.
AND. API Gateway accepts only the responses that
contain all configured HTTP headers.
OR. This is selected by default. API Gateway accepts
responses that contain at least one configured HTTP
header.
M
Even Header
Policies
HTTP Header Key. Specifies a key that must be passed

through the HTTP header of the incoming API responses.
Header Value. Optional. Specifies the corresponding key
value that could be passed through the HTTP header of
the incoming API responses.
The Header Value field type accepts string and regular
expression (regex).
You can add more HTTP headers by clicking .
Data Masking
This policy is used to mask sensitive data at the application level. At the application level
you must have an Identify and Access policy configured to identify the application for
which the masking is applied. If no application is specified then it will be applied for all
the other responses. Fields can be masked or filtered in the response messages to be sent.
You can configure the masking criteria as required for the XPath, JSONPath, and Regex
expressions based on the content-types. This policy can also be applied at the API scope
level.
The table lists the content-type and masking criteria mapping.
Content-type Masking Criteria
application/xml XPath
text/xml
text/html
application/json JSONPath
application/json/
badgerfish
text/plain Regex
the response messages:
M
Odd Header
Policies
Consumer Optional. Specifies the applications for which the masking

Applications criterion has to be applied.
For example: If there is a DataMasking(DM1) criteria
created for application1 a second DataMasking(DM2) for
application2 and a third DataMasking(DM3) with out any
application, then for a request that comes from consumer1
the masking criteria DM1 is applied, for a request that
comes from consumer2 DM2 is applied. If a request comes
with out any application or from any other application
except application1 and application2 DM3 is applied.

XPath: Specifies the masking criteria for XPath expressions in the response
messages.
to be masked or filtered.
For example: /pet/details/status, /user/details/card/
ccnumber.
is Mask. Provide a mask value. For example: sold, any
mask value #####.

information:
M
Even Header
Policies


by clicking .
JSONPath. This is applicable only for REST API. Specifies the masking criteria for
JSONPath expressions in the response messages.
Query expression. Specify the query expression
that has to be masked or filtered. For example:
$.pet.details.status
Mask. Provide a mask value. For example: sold
Regex. Specifies the masking criteria for regular expressions in the response
messages.
to be masked or filtered. For example: [0-9]+
Mask. Provide a mask value. For example: ########
transaction logs.
Logging
M
Odd Header
Policies
Apply for payload Select this option to apply masking criteria for payload in
the response message.
CORS
The Cross-Origin Resource Sharing (CORS) mechanism supports secure cross-domain
requests and data transfers between browsers and web servers. The CORS standard
works by adding new HTTP headers that allow servers to describe the set of origins that
are permied to read that information.
This policy uses CORS support that uses additional HTTP headers to let a client or
an application gain permission to access selected resources. An application or a client
makes a cross-origin HTTP request when it requests a resource from a different domain,
protocol, or port than the one from which the current request originated.
This policy is applicable only for REST-based APIs.
The table lists the CORS response specifications, you can specify for this policy:
Allowed Origins Specifies the origin from which the responses originating
are allowed.
syntax for the origin: scheme ://host :port
You can add multiple origins by clicking .
You can also provide Regular expressions for allowed

origins.
Allowed origins can also be specified in the Advanced
section under Applications. Allowed origins of applications
registered with this API are also allowed to access this API.
Max Age Specifies the age for which the preflight response is valid.
Allowed Methods Specifies the methods that are allowed in the request.
Specify one or more of the following: GET, POST, PUT,
DELETE, and PATCH.
Allow Headers Specifies the Headers that are allowed in the request.
M
Even Header
Policies
You can add multiple headers that are to be allowed by

clicking .
Allow Credentials Specifies whether the request credentials could be exposed

to the user on request failure.
Expose Headers Specifies the headers that be exposed to the user on request
failure.
You can add multiple headers that are to be allowed by
clicking .
A corresponding HTTP header is set for all the values above as per the specification. For
additional information, see “hps://www.w3.org/TR/cors/”.
Error Handling
The policy in this stage enables you to specify the error conditions, lets you determine
how these error conditions are to be processed. You can also mask the data while
processing the error conditions. The policies included in this stage are:
Conditional Error Processing
Data Masking
Conditional Error Processing

Error Handling is the process of passing an exception message issued as a result of a
run-time error to take any necessary actions. This policy returns a custom error message
(and the native provider's service fault content) to the application when the native
provider returns a service fault. You can configure conditional error processing and use
variables to create custom error messages.
Error conditions. Specifies the error conditions and how these error conditions
should be processed.
Status Code Error Specify the error status code.

Criteria
Provide a value for the Code.
M
Odd Header
Policies
Header Error Criteria Provide the details of the custom HTTP header(s)
included in the client requests.
Header Name. Specifies the name of the HTTP header.
Header Value. Specifies the value of the HTTP header.
Payload Criteria Provide the details of the payload criteria in the API
request.
Add.
Expression type. Specifies the type of expression,
which is used for identification. You can select one the
following expression type:
expression that the specified XPath expression
type in the request or the response has to be
converted to. For example: /name/id.
The response maybe a native service error or
API Gateway generated error.

URI by clicking .
JSONPath. Provide the Payload Expression that

specifies the payload expression that the specified
JSONPath expression type in the request or the
response has to be converted to. For example:
$.name.id.
The response maybe a native service error or API
Gateway generated error.
Text. Provide the Payload Expression that specifies
the payload expression that the specified Text
M
Even Header
Policies
expression type in the request or response has to
be converted to. For example: any valid regular
expression.
The response maybe a native service error or API
Gateway generated error.

allowed. For example, you can add a maximum
of three payload identifiers, each being of a
different type.
Value: Specifies a value that has to match with the value

contained in the error Response.
Pre-Processing. Specifies how the native error response is to be processed before

API Gateway processes it. .
Invoke webMethods Specify the webMethods IS service to pre-process the

Integration Server error message.
Service
Provide the following information
webMethods IS Service. Specify the webMethods
IS service to be invoked to pre-process the error
pre-process the service error message.
You can add multiple entries for webMethods IS
service by clicking .

want API Gateway to use to run the IS service.
webMethods IS Service alias. Start typing the
webMethods alias name and select the alias from the
M
Odd Header
Policies
type-ahead search results displayed to add one or
more aliases.
XSLT Transformation Provide the XSLT file and feature you want to use to
transform the service error response.
Click Browse to select the XSLT file and upload it.
Provide the following information for the XSLT
feature:
Feature Value. Specifies the value for the feature.
You can add multiple entries for feature name and
value by clicking .
Custom Error Variables. Specifies the error variables to be used in the custom error
message.
Payload Type Specify the payload type.

Request. Specifies the request payload type.
Response. Specifies the response payload type.
Name Provide a name for the payload type.
Payload Identifier Provide the details of the payload criteria in the API
request.
Add.
Expression type. Specifies the type of expression
contained in the payload request.
Payload Expression. Specifies the payload expression
that the specified expression type in the request has to
be converted to.
M
Even Header
Policies
Note: You can add multiple namespace prefix and

URI using the Add buon.
Failure Message. Specifies the custom failure message format that API Gateway
should send to the application. Specify whether the message should be in the
text, json, or xml format.
Send Native Provider Enable this parameter so that API Gateway sends
Fault Message the native SOAP or REST failure message to the
application.
When you disable this parameter, the failure message
is ignored when a fault is returned by the native API
provider.
Post-Processing. Specifies how the error response sent by the native service is to
be processed before sending the same to the application.
Invoke webMethods Specify the webMethods IS Service for post-processing

Integration Server the error message.
Service
Provide the following information
webMethods IS Service. Specify the webMethods
IS service to be invoked to post-process the error
post-process the service error message.
You can add multiple entries for webMethods IS
service by clicking .

want API Gateway to use to run the IS service.
M
Odd Header
Policies
webMethods IS Service alias. Start typing the

webMethods alias name and select the alias from the
type-ahead search results displayed to add one or
more aliases.
XSLT Transformation Provide the XSLT file that you want to use to transform
the service error response.
Provide the following information for the XSLT
feature:
Feature Value. Specifies the value for the feature.
You can add multiple entries for feature names and
values by clicking .
Data Masking
This policy is used to mask sensitive data in the custom error messages being processed
and sent to the application. Fields can be masked or filtered in the error messages.
You can configure the masking criteria as required for the XPath, JPath, and Regex
expressions. This policy can also be applied at the API scope level.
the request messages received:
Consumer Specifies the applications for which the masking criterion

Applications has to be applied.

XPath. Specifies the masking criteria for XPath expressions in the error messages.
M
Even Header
Policies
Masking Type. Specifies the type of masking required. You
select either Mask or Filter.
to be masked or filtered. For example: /soapenv:Fault/
faultstring
is Mask. Provide a mask value. For example: Error
occurred while processing the request. Please check your
input request or any other meaningful message or
string.

information:

by clicking .
JPath. This is applicable only for REST API. Specifies the masking criteria for
JPath expressions in the error messages.
to be masked or filtered. For example: $.error.reason
string.
M
Odd Header
Policies
Regex. Specifies the masking criteria for regular expressions in the error
messages.
to be masked or filtered. For example: (.*)
string.
transaction logs.
Logging
Apply for payload Select this option to apply masking criteria for payload.
The API for Context Variables

API Gateway provides an API that you can use to:
Set, get, declare, and remove custom context variables.
Set and get the predefined context variables. (It is not allowed to declare or remove
the predefined context variables.)
API Gateway provides the following JAVA services, which are defined in the class
ISMediatorRuntimeFacade.java:
pub.apigateway.ctxvar:getContextVariable
pub.apigateway.ctxvar:setContextVariable
pub.apigateway.ctxvar:declareContextVariable
pub.apigateway.ctxvar:removeContextVariable
pub.apigateway.ctxvar:getContextVariable
Use this JAVA service to retrieve a context variable’s value and assign it to a pipeline
variable. All parameter names are case-sensitive.
M
Even Header
Policies
Parameter Pipeline Data Description Examples

Type Type
MessageContext
in Object This object is inserted N/A
ref into the pipeline by
API Gateway.
varName in String Context variable PROTOCOL_HEADERS

name (predefined or mx:CUSTOM_VAR
custom).
serValue out Object Java.io.serializable

ref value. (Usually a
string).
Notes on getting and setting the PROTOCOL_HEADERS

All context variable values are typed as either string or int except for the predefined
context variables, PROTOCOL_HEADERS, which is of the type IData. You can set or get
value for PROTOCOL_HEADERS in one of the following ways:
set or get the entire structure.
To set the entire structure, you must:
Set the varName parameter in pub.apigateway.ctxvar:setContextVariable
to PROTOCOL_HEADERS.
Use the method ISMediatorRuntimeFacade.setContextVariableValue().
To get the entire structure, you must:
Set the varName parameter in pub.apigateway.ctxvar:getContextVariable
to PROTOCOL_HEADERS.
Use the method ISMediatorRuntimeFacade.getContextVariableValue().
If the varName is set to PROTOCOL_HEADERS, you get or set the entire IData
structure containing all of the transport headers. The key is the transport header
name (for example, Content-Type) and the value is a String. The IData object for
PROTOCOL_HEADERS contains a set of string values where each IData string key
matches the header name in the transport headers map. The set of possible keys
includes the HTTP v1.1 set of headers as well as any custom key-value pairs you
might have defined.
Alternatively, you can set the varName parameter to address a specific element in
the array. For example, seing it to PROTOCOL_HEADERS[Content-Type] would
apply to the Content-Type transport header.
set or get a nested value.
M
Odd Header
Policies
Set a nested value in one of the following ways:

Set the varName parameter in pub.apigateway.ctxvar:setContextVariable
to PROTOCOL_HEADERS[arrayElement], where [arrayElement] refers to a
specific element. For example, PROTOCOL_HEADERS[Content-Type] (to indicate
the first array element in the set).
Alternatively, use the method
ISMediatorRuntimeFacade.setContextVariableValue(). Use this method
only if you are writing a JAVA service and you want to access it through the
JAVA source code.
Get a nested value in one of the following ways:
Set the varName parameter in pub.apigateway.ctxvar:getContextVariable
to PROTOCOL_HEADERS[arrayElement], where [arrayElement] refers to a
specific element. For example, PROTOCOL_HEADERS[Content-Type] (to indicate
the first array element in the set).
Alternatively, use the method
ISMediatorRuntimeFacade.getContextVariableValue(). Use this method
only if you are writing a JAVA service and you want to access it through the
JAVA source code.
You can set or get a nested value inside PROTOCOL_HEADERS through an
additional keyName. In this case, the object reference is not an IData object. For
PROTOCOL_HEADERS, the keyName must match the transport header name
in a case-sensitive manner (for example, PROTOCOL_HEADERS[Content-Type] or
PROTOCOL_HEADERS[Authorization]). In this case, the Serializable value will be a
string.
pub.apigateway.ctxvar:setContextVariable
Use this JAVA service to set a value on a context variable. The pipeline variable
containing the context variable value should be an object reference that implements
java.io.Serializable. All parameter names are case-sensitive.

Type Type
MessageContext
in Object This object is N/A
ref inserted into the
pipeline by API
Gateway.
varName in String Context variable PROTOCOL_HEADERS

name (predefined
mx:CUSTOM_VAR
or custom).
M
Even Header
Policies

Type Type
serValue in Object Java.io.serializable

ref value. (Usually a
string).
pub.apigateway.ctxvar:declareContextVariable
Use this JAVA service to declare a custom context variable. All custom-defined context
variables must be declared in a custom namespace that is identified by using the prefix
mx (for example, mx:CUSTOM_VARIABLE). All parameter names are case-sensitive.
Note: It is not legal to use this service to declare the predefined context variables;
you can only declare custom variables.
Parameter Pipeline Data Description

Type Type
ctxVar in Object The document type defining the context

ref variable object. Use the ctxVar Document
Type provided in the JAVA service
pub.apigateway.ctxvar:ctxVar and map it to this
input variable. Define the name (for example,
mx:CUSTOM_VARIABLE), the schema_type
(string or int), and isReadOnly (true or false).
ctxVar out Object The set Context variable document type.

ref
varNameQ out Object javax.xml.namespace.QName value. The

ref QName of the variable.
Note the following:

After declaring the context variable, you can use the setContext variable to set a
value on the context variable.
You do not need to declare the following kinds of context variables:
The predefined context variables provided by API Gateway. If you aempt to
declare an existing predefined context variable, an error will occur.
Any custom context variable that you define in a routing rule that you create in
the context-based routing step.
Any custom context variables that you explicitly declare in source code using the
API will have a declaration scope of SESSION.
M
Odd Header
Policies
Any custom context variable's state that is defined during the inbound request
processing steps will still be available during the outbound response processing
steps.
All context variable values are typed as either string or int (excluding the
PROTOCOL_HEADERS variables, which are of the type IData).
Valid names should be upper case (by convention) and must be a valid JAVA
Identifier. In general, use alpha-numerics, $ or _ symbols to construct these context
names. Names with punctuation, whitespace or other characters will be considered
invalid and will fail deployment.
All custom context variables must be declared in a custom namespace that is
identified by using an mx prefix (for example, mx:CUSTOM_VARIABLE).
To reference a custom context variable in a flat string, you need to prepend a $
symbol to the context variable name to indicate that variable’s value should be
referenced. Think of this usage as being similar to the & address operation for C
variables.
An expression that references a custom context variable might look like this:
$mx:TAXID=1234 or $mx:ORDER_SYSTEM_NAME="Pluto"
Notice that the values of the data type “int” are not enclosed in quotation marks,
while the values of the data type “string” are. The quotation marks are only needed
if a context variable expression (as opposed to a reference) is defined.
Referencing an undefined context variable does not result in an error.
Once a variable has been declared it cannot be declared again.
pub.apigateway.ctxvar:removeContextVariable
Use this JAVA service to remove a custom context variable from a request or response
session. All parameter names are case-sensitive.
Note: Keep the following points in mind:

It is not legal to use this service to remove any predefined context
variables; you can only remove custom variables.
Aempting to remove a non-existent context variable will not result in an
error.

Type Type
MessageContext
in Object This object is inserted N/A
ref into the pipeline by
API Gateway.
M
Even Header
Policies

Type Type
varName in String Custom context mx:CUSTOM_VAR

variable name.
Sample Flow Service: Getting a Context Variable Value

This flow service sets the value of a custom context variable to be used in a response.
This flow service declares a pipeline variable named customName, which is set to the
value mx:COMP_TEST.
This flow service will retrieve the context variable for customName and create an element
for its context variable value in the response message return to the consumer.
M
Odd Header
Policies
Step 1. Declaring customName
We define the customName variable value to be mx:COMP_TEST so we can use this

variable to lookup the custom variable name that was seeded in the previous example.
M
Even Header
Policies
Step 2. Setting customName to mx:COMP_TEST
Clicking on the customName pipeline variable displays the name.
M
Odd Header
Policies
Step 3. Displaying the value of customName
The call to pub.mediator.ctxvar:getContextVariable retrieves the value of the

custom context variable from the context variable map.
M
Even Header
Policies
Step 4. Calling meditor.ctxvar:getContextVariable
This is just a sample JAVA service that takes the context variable and creates a top-level
element in the response message using the same name and value.
M
Odd Header
Policies
Step 5. Sample service using the context variable
Sample Flow Service: Setting a Context Variable Value

This flow service sets the value of a custom context variable to be used in a response.
This flow service declares a pipeline variable named customName, which is set to the
value mx:COMP_TEST.
This flow service will retrieve the context variable for customName and create an element
for its context variable value in the response message return to the consumer.
M
Even Header
Policies
Step 1. Declaring customName
We define the customName variable value to be mx:COMP_TEST so we can use this

variable to lookup the custom variable name that was seeded in the previous example.
M
Odd Header
Policies
Step 2. Setting customName to mx:COMP_TEST
Clicking on the customName pipeline variable will display the name.
M
Even Header
Policies
Step 3. Displaying the value of customName
The call to pub.mediator.ctxvar:getContextVariable retrieves the value of the

custom context variable from the context variable map.
M
Odd Header
Policies
Step 4. Calling meditor.ctxvar:getContextVariable
This is just a sample JAVA service that takes the context variable and creates a top-level
element in the response message using the same name and value.
M
Even Header
Policies
Step 5. Sample service using the context variable
Managing Global Policies

Important: API Gateway's Standard Edition License does not support the functionality
of Global Policies. You can create and manage global policies only using the
Advanced Edition License.
Global policies are a set of policies that are associated globally to all APIs or the selected
set of APIs. Global policies are supported for both SOAP and REST APIs.
By associating policies globally to all APIs or the selected set of APIs, the administrator
can ensure that a set of policies is applied to the selected APIs by default. The
administrator can, for example, define a global policy that aaches a WS-Security (WSS)
authentication to all SOAP API endpoints within a specific IP range. In this case, any
M
Odd Header
Policies
client request from the specific IP range automatically inherits the security configuration
defined in the global policy for SOAP APIs.
Global Policy Matrix

This table lists the stage-specific policies that can be configured as global policy for
different types of APIs at the global level.
Note: The Policy configuration page displays only the policies that are common to one
or more API types selected in the global policy filter.
Stages Policies
Transport Require HTTP/HTTPS - This policy can be enforced for all types
of API. But the SOAP versions 1.1 and 1.2 are applicable only for
SOAP-based APIs. The SOAP 1.1 and SOAP 1.2 sub types are not
available in UI when the REST and ODATA APIs are selected.
Note: Software AG recommends to create a separate policy for

each API type.
Set Media Type - This policy is applicable only for a REST request
and the policy name is not listed in Policy configuration page when the
SOAP and ODATA APIs are selected.
Require JMS - The Require JMS policy is applicable only for SOAP
APIs and the policy name is not listed in Policy configuration page
when the REST and ODATA APIs are selected.
Identity Inbound Authentication - Transport, Authorize User, Identify and

& Authorize Application - These policies can be enforced to any API
Access Type.
Inbound Authentication - Message - This policy is applicable only
for SOAP-based APIs and the policy name is not listed in Policy
configuration page when the REST and ODATA APIs are selected.
Request Invoke webMethods IS, Validate API Specification, Data Masking -

Processing These policies can be enforced to any API Type.
Request Transformation - This policy is applicable only for SOAP
and REST APIs. and not for ODATA services. When all three API
types are selected, Request Transformation policy cannot be applied
at the global level.
Routing Custom HTTP Header, Outbound Authentication - Transport,

Outbound Authentication - Message. The Routing stage policies can
be applied at a global level for all types of API.
M
Even Header
Policies
Stages Policies
Traffic Log Invocation, Monitor Service Performance, Monitor Service Level

Monitoring Agreement, Throling Traffic Optimization, and Service Result
Cache. The Traffic Monitoring stage policies can be applied at a
global level for all types of API.
Response Invoke webMethods IS, Validate API Specification, Data Masking -

Processing These policies can be enforced to any API Type.
Response Transformation - This policy can be enforced only for
SOAP and REST APIs and the policy name is not listed in Policy
configuration page when ODATA API type is selected.
CORS - This policy can be enforced only for REST and ODATA APIs
and the policy name is not listed in Policy configuration page when
SOAP-based API is selected.
Error Conditional Error Processing and Data Masking. The Error handling
handling stage policies can be applied at a global level for all types of API.
Creating a Global Policy

You must have the API Gateway's manage global policies functional privilege assigned.
To create a global policy you must perform the following high-level steps:
1. Create a new global policy: During this step, you specify the basic details of the global
policy.
2. Optionally refine the scope of the policy: During this step, you can specify additional
criteria to narrow the set of APIs to which the global policy applies.
3. Configure the policies: During this step, you associate one or more policies, and assign
values to each of the associated policy's properties.
4. Activate the policy: During this step, you put the new global policy into effect.
To create a global policy

2. Click the Global Policies tab.
A list of all available global policies appears.
3. In the Policies page, click the Create Global Policy buon.
If you do not see the Create Global Policy buon, it is probably because you do not
have the API Gateway Administrator role to create a global policy in API Gateway.
This opens the Create Global Policy page with the default Policy Details tab.
M
Odd Header
Policies
4. In the Basic Information section, provide the required information for each of the
displayed data fields:
Field Description
Name Name of the global policy.
Description Description of the global policy.
5. Click Save to save the new (as yet incomplete) global policy.
6. Complete the new global policy by doing the following:
a. On the Filters section, specify the API types, additional criteria for selecting the
APIs to which you want the global policy to be applied, logical operator for the
selection criteria, and the APIs to which the global policy applies. For details,
see “ Modifying the Scope of a Global Policy” on page 357 and “ Refining the
Scope of a Global Policy” on page 358.
b. On the Policy Configuration tab, choose the policies and configure the properties
for each policy that you want API Gateway to execute when it applies this global
policy. For details, see “ Associating Policies to a Global Policy” on page 361
and “ Configuring Properties for a Global Policy” on page 362.
c. Activate the global policy when you are ready to put it into effect. For details, see
“ Activating a Global Policy” on page 365.
Modifying the Scope of a Global Policy

Scope refers to the set of properties that determine a selected set of APIs for the
enforcement of the policy. For a global policy, scope is determined by the policy's
property API Type in the Policy Details tab.
API Type Description
REST Global policy will be applied on all REST APIs

in API Gateway.
SOAP Global policy will be applied on all SOAP APIs

in API Gateway.
To modify the scope of a global policy

M
Even Header
Policies

3. Select the required policy.
The Global Policy details page appears.
4. Click Edit.
If you do not see the Edit buon, it is probably because you do not have the API
Gateway Administrator role to modify the scope of a global policy in API Gateway.
5. Select the policy's Filters section, and specify the following:
a. In the API Type property, select the API types (REST, SOAP, or both) to which the
policy will be applied.
b. Optional. In the Filter using… section, specify additional selection criteria to
narrow the set of APIs to which this policy will be applied. For details, see “
Refining the Scope of a Global Policy” on page 358.
6. Click Save.
Refining the Scope of a Global Policy

If you want to further restrict the set of APIs to which the global policy is applied, you
can specify additional selection criteria in the Filter section of the API details page.
Using the Filter section, you can filter APIs by Name, Description, Version aributes,
and HTTP Methods (applicable only for REST APIs). If you specify no filter criteria, the
global policy will apply to all of the selected APIs.
Filtering by Name, Description, and Version attributes
You can filter APIs based on their Name, Description, and Version aributes using any
of the following comparison operators:
Comparison Operators Description
Equals Selects APIs whose Name, Description, or Version

value matches a given string of characters. For
example, use this operator to apply a policy only to
REST APIs with the Name or Description value 4G
Mobile Store.
Not Equals Selects APIs whose Name, Description, or Version

value does not match a given string of characters. For
example, use this operator to apply a policy only to all
REST APIs except those with the Name or Description
value Mobile.
M
Odd Header
Policies
Comparison Operators Description
Contains Selects APIs whose Name or Description value

includes a given string of characters anywhere within
the aribute's value. For example, use this operator to
apply a policy to REST APIs that had the word Mobile
anywhere in their Name or Description aribute.
Starts with Selects APIs whose Name or Description value begins

with a given string. For example, use this operator
to apply a policy only to REST APIs whose Name or
Description begins with the characters 4G.
Ends with Selects APIs whose Name or Description value ends

with a given string. For example, use this operator
to apply a policy only to REST APIs whose Name or
Description ends with the characters Store.
When specifying match strings for the comparison operators described above, keep the
following points in mind:
Match strings are not case-sensitive. If you define a filter for names that start with ABC
it will select names starting abc and Abc.
Wildcard characters are not supported. That is, you cannot use characters such as *
or % to represent any sequence of characters. These characters, if present in the match
string, are simply treated as literal characters that are to be matched.
Filtering by HTTP Methods (Applicable only for REST APIs)
You can optionally restrict a policy to specific HTTP methods of the REST APIs by
specifying the following options - GET, POST, PUT, DELETE, and PATCH.
HTTP Methods Description
GET Policy applies only to HTTP GET requests for any

resource in the API. For example, use this option to
apply a policy to resources of a REST API during an
incoming GET request.
POST Policy applies only to HTTP POST requests for any

incoming POST request.
PUT Policy applies only to HTTP PUT requests for any

M
Even Header
Policies
HTTP Methods Description

incoming PUT request.
DELETE Policy applies only to HTTP DELETE requests for

any resource in the API. For example, use this option
to apply a policy to resources of a REST API during
an incoming DELETE request.
PATCH Policy applies only to HTTP PATCH requests for any

incoming PATCH request.
To refine the scope of a global policy

4. Click Edit.
Gateway Administrator role to refine the scope of a global policy in API Gateway.
5. Click Filters.
6. To filter by Name, Description, or Version, take the following steps in the Filter using
API Aributes section:
a. Select API Name, API Description, or API Version in the first field.
b. Select the comparison operator in the second field.
c. Specify the match string in the third field.
d. To specify additional criteria, click the Add buon and repeat the above steps.
e. Select the logical conjunction (AND) or disjunction (OR) operation to apply when
multiple criteria are specified for the global policy. The default value is AND.
7. Applicable only for REST APIs. To filter by HTTP methods, in the Filter using HTTP
Methods section, select the HTTP methods by which you want to filter APIs with
appropriate incoming requests.
8. Click Save to save the updated policy.
M
Odd Header
Policies
Associating Policies to a Global Policy

The Policy Configuration tab on the Global Policy details page specifies the policy stages
and the list of policies (applicable for each stage) that you want API Gateway to execute
when it enforces the global policy.
When modifying the list of policies for a global policy, API Gateway validates the
policies to ensure that there are no policy conflicts.
To modify the list of policies of a global policy

4. Click Edit.
Gateway Administrator role to modify the list of policies of a global policy in API
Gateway.
5. Select the policy's Policy Configuration tab.
The policy information is provided in the following sections:
Policy catalog - Transport, Identify and Access, Request Processing, Routing,
Traffic Monitoring, Response Processing, Error Handling
Infographic - List of applied policies
Policy properties - Collection of policy properties
6. In the Policy catalog section, click the chevron to expand the required policy stage.
This displays a list of policies that are classified under the particular stage.
7. In the expanded list of policies, select the policies that you want API Gateway to
execute when it applies this global policy. To select a policy, click the Add (+) icon
next to the policy name. The selected policies are displayed in the Infographic
section.
When you select the policies for the global policy, keep the following points in mind:
The policies shown in the Policy catalog section are determined by the API types
that you have specified on the Filters section of the Global Policy Details page.
If you do not see a policy that you need, that policy is probably not compatible
with the API type that you selected in the Filters section.
M
Even Header
Policies
If necessary, you can click the Policy Details tab and change your API type
selection.
Use the x icon in any individual policy to remove that particular policy from the
Infographic section.
8. To configure the properties for any new policies that you might have added to the
Infographic section in the preceding steps or to make any necessary updates to the
properties for existing policies in the global policy, see “ Configuring Properties for a
Global Policy” on page 362.
9. Click Save.
10. Click to view the complete list of policies in the updated policy.
The Overview buon is located in the lower right-corner of the Infographic section.
To exit the overview, click the Close icon.
Configuring Properties for a Global Policy

The Policy Configuration tab on the Global Policy details page specifies the list of policies
that are applicable for each policy stage in the Policy catalog section. Each policy
in the Infographic section has properties that you must set to configure the policy's
enforcement behavior.
To configure the properties for a global policy

4. Click Edit.
Gateway Administrator role to configure the properties of a global policy in API
Gateway.
5. Select the policy's Policy Configuration tab.
The policy information is provided in the following sections:
M
Odd Header
Policies
7. In the Infographic section, do the following for each policy in the list:
a. Select the policy whose properties you want to examine or set.
b. In the Policy properties section, set the values for the policy's properties as
necessary.
Note: Required properties are marked with an asterisk.
8. Click Open in full-screen to view the policy's properties in full screen mode.
The Open in full-screen link is located in the upper right-hand corner of the Policy
Configuration tab. Set the properties of the displayed policy, and then click OK.
To exit out of full screen mode, click the Minimize icon.
9. Click Save.
10. Click to view the complete list of policies in the updated policy.
Viewing List of Global Policies and Policy Details

The Global Policies tab displays a list of all globally available policies in API Gateway.
Global policies are listed alphabetically by name.
In addition to viewing the list of policies, you can also examine the details of a policy,
create a copy of the template, activate, and delete a global policy in the Global Policies tab.
To view the policy list and properties of a global policy

The Global Policies tab provides the following information about each policy:
Column Description
Description The description for the global policy.
You can also perform the following operations on a global policy:
M
Even Header
Policies
Activate a policy to begin enforcing runtime behaviors.

Deactivate a policy to suspend enforcement of runtime behaviors.
Create a new copy of the policy.
Delete a policy to remove it from API Gateway.
3. Select the required policy whose details you want to examine.
The Global Policy details page appears. The policy details are displayed in the
following tabs:
Policy Details: This tab contains a summary of basic information such as name,
description, scope of the policy as to when the policy will apply, applicable APIs,
and other information.
Policy Configuration: This tab contains the policy stages, applied policies, as well as
the configuration details of individual policies.
Modifying Global Policy Details

You use the Global Policy details page to examine and modify the properties of a policy.
When modifying the details of a global policy, keep the following points in mind:
You will not be allowed to save the policy unless all of its properties have been set.
On successful modification of the policy details for an active global policy, the policy
changes apply with immediate effect in all the active APIs that are applicable for this
global policy.
You will not be allowed to remove an individual policy (for example, Identify
and Authorize Application) from the active global policy, if the global policy is
already applied to an active API, and if the Identify and Authorize Application is a
dependent policy for another policy (for example, Throling Traffic Optimization)
that is applied for the API.
If modification of the policy details for an active global policy fails, API Gateway
issues an error message with details of the incompatible or conflicting policies.
To modify the properties of a global policy

The Global Policy details page appears. The policy details are displayed in the
following tabs:
M
Odd Header
Policies
Policy Details: This tab contains a summary of basic information such as name,
description, scope of the policy as to when the policy will apply, applicable APIs,
and other information.
4. Click Edit.
Gateway Administrator role to modify the properties of a global policy in API
Gateway.
5. On the Policy Details tab, modify the basic properties, selection criteria, and the
applicable APIs as necessary.
6. On the Policy Configuration tab, modify the policy list and the policy's configuration
properties as necessary.
7. When you have completed the required modifications in the Global Policy details
page, click Save to save the updated policy.
8. Click Overview to view the complete list of policies in the updated policy.
Activating a Global Policy

You must have the API Gateway's activate global policies functional privilege assigned.
Global policies are not enforced until they are activated.
When you activate a global policy, be aware that:
When a global policy becomes active, API Gateway begins enforcing it immediately
in all the applicable APIs that are currently in the Active state. You can suspend
enforcement of a policy by switching it to the Inactive state as described in “
Deactivating a Global Policy” on page 366.
Activation of a global policy fails if there is a conflict in the effective policy validation
in at least one of the active APIs that are applicable for this policy. API Gateway
reports the conflict, and the global policy can only be activated when the conflict is
resolved.
To determine whether a global policy is active or inactive, examine the policy's Active
indicator on the Policies > Global Policies tab. The icon in the Active column indicates the
policy's activation state as follows:
M
Even Header
Policies
Icon Description
Policy is active.
Policy is inactive.
The activation state of a policy is also reported in the Global Policy Details page.
To activate a global policy

4. Click Activate.
If you do not see the Activate buon, it is probably because you do not have the API
Gateway Administrator role to activate a global policy, or the policy is already in an
Active state in API Gateway.
Deactivating a Global Policy

You must have the API Gateway's activate global policies functional privilege assigned.
Deactivating a global policy causes API Gateway to suppress enforcement of the policy.
You usually deactivate a policy to suspend enforcement of a particular policy
(temporarily or permanently).
To deactivate a policy, you change the policy to the Inactive state. At a later time, you
can begin enforcing a global policy by switching it to the Active state as described in “
Activating a Global Policy” on page 365.
When you deactivate a global policy, be aware that:
Deactivation of a global policy fails if there is a conflict in the effective policy
validation in at least one of the active APIs that are applicable for this policy. API
Gateway reports the conflict, and the global policy can only be activated when the
conflict is resolved.
To determine whether a global policy is active or inactive, examine the policy's Active
indicator on the Policies > Global Policies tab. The icon in the Active column indicates the
policy's activation state as follows:
M
Odd Header
Policies
Icon Description
Policy is active.
Policy is inactive.
The deactivation state of a policy is also reported in the Global Policy Details page.
To deactivate a global policy

4. Click Deactivate.
If you do not see the Deactivate buon, it is probably because you do not have the
API Gateway Administrator role to deactivate a global policy, or the policy is already
in an Inactive state in API Gateway.
Deleting a Global Policy

You delete a global policy to remove it from API Gateway permanently.
To delete a global policy, the following conditions must be satisfied:
The policy must not be in-progress.
The policy must be inactive.
To delete a global policy

3. Click the Delete ( ) icon for the required policy.
If you do not see the Delete buon, it is probably because you do not have the API
Gateway Administrator role to delete a global policy, or the policy is in an Active
state in API Gateway.
M
Even Header
Policies
Copying a Global Policy

A global policy can become quite complex, especially if it includes many policies.
Instead of creating a new policy from scratch, it is sometimes easier to copy an existing
policy that is similar to the one you need and edit the copy.
When you create a copy of a global policy, be aware that:
When API Gateway creates a copy of a policy, the new copy of the policy is identical
to the original one.
Like all new policies, the copied policy is marked as Inactive.
There is no expressed relationship between the copy and the original policy (that is,
API Gateway does not establish any type of association between the two policies).
In general, a copied policy is no different from a policy that you create from scratch.
To copy a global policy

3. Click the Copy icon for the required policy.
If you do not see the Copy buon, it is probably because you do not have the API
Gateway Administrator role to create the copy of a global policy in API Gateway.
4. In the Copy of Global Policy dialog box, provide the required information for each of
the displayed data fields:
Field Description

API Gateway automatically adds the name of
the existing global policy to the Name field. You
can change the name of the policy to suit your
needs. But you cannot leave this field empty.
Description The description for the global policy.
5. Click Copy to save the new policy.

6. Modify the new policy as necessary and then save it.
Activate the new policy when you are ready to put it into effect.
M
Odd Header
Policies
Exporting Global Policies

You must have the API Gateway's export assets functional privilege assigned.
To export the global policies

2. Select Global Policies.
3. Click to export a single policy.
Alternatively, you can select multiple APIs to be exported simultaneously by clicking
the checkboxes adjacent to the names of the API.
Click and select Export from the drop-down list.

The browser prompts you to either open or save the export archive.
Managing API-level Policies

The API-level policies apply to all APIs at the API level within an instance of API
Gateway.
A policy at an API-level provides run-time governance capabilities to an API. The policy
can be used to identify and authenticate consumers, validate digital signatures, capture
performance measurements, and so on. Policies have one or more properties, which
you can configure in a policy when you apply it to an API. For example, a policy that
identifies consumers specifies one or more identifiers to identify the consumers who are
trying to access the API.
The API level policies are categorised in the following stages:
Threat protection - These policies can be viewed on the API details page of an API
but can be managed only through the Policies > Global threat protection section and
cannot be managed from the API details page.
Transport
Identify & Access
Request Processing
Routing
Traffic Monitoring
Response Processing
Error Handling
M
Even Header
Policies
Assigning a Policy to an API

Ensure that the API is in Edit mode before you start assigning a policy to the API.
To assign a policy to an API

3. Click the Policies tab.
4. Select the policy stage and the required policy.
The policy is displayed in the infographic with its properties displayed in properties
section.
5. Provide the properties for the selected policy.
6. Click Save.
The policy is assigned to the API.
Viewing API Policy Details

The Policies tab on the API details page specifies the set of policies that are applied for
that particular API.
The API can have a set of policies that are configured globally through a policy, or
directly through a policy template or a scope-level policy.
The global policy in an API details page has each of its policies differentiated using a
specific icon from the rest of the policies that are defined at the API-level and scope-
level. The icon in the policy indicates the Inbound Authentication - Transport policy's
enforcement level within an API:
Icon Description
Policy is applied from a global policy. This

policy is applicable across all resources /
methods / operations of all APIs.
Policy is applied from a policy template or at

the API definition. This policy is applicable
across all resources / methods / operations of
that particular API.
M
Odd Header
Policies
Icon Description
Policy is applied for the API's scope. This

policy is applicable across a set of resources /
methods / operations of that particular API.
Policy is applied through an active package

definition. This policy is applicable across
all resources / methods / operations of that
particular API.
Unlike the policy defined at API-level or scope-level, the policy defined as part of a
global policy cannot be edited or deleted through the details page of an API.
To view the policy details of an API

The Infographic view displays policies configured for the API.
When this API is associated with one or more plans through active packages, a list
of the Identify and Authorize Application policies and Threat Protection policies that are
inherited from the corresponding plans and enforced on the API also appears. The
inherited policies are differentiated using the package icon. The Identify and
Authorize Application policy by default has the Identification Type set to API Key.
4. Click .
A list of all available policies enforced on the API appears.
Modifying API Policy Details

Ensure that the API is in Edit mode before you modify a policy that is assigned to the
API.
To modify the policy details of an API

4. Select the policy stage, and the required policy.
M
Even Header
Policies
The Infographic view displays policies configured for the API.

5. You can do one of the following:
Add more policies to the API. Select the policy stage and add the required policy.
Configure the properties for the newly added policy as required.
Modify the already configured policy. Click the Edit icon. Select the required
policy and modify the properties as required.
Delete policies from the API. To remove a policy, click the x icon.
6. Click Save.
Managing Scope-level Policies

You can define policies at the API-level or scope-level for an API. API-level policies are
processed for all incoming requests to the API. Scope-level policies are processed only
for incoming requests that apply to a specific scope in the API. Any policy you specify
at the API-level is overridden by the policy defined at the scope-level if the policies are
the same. In contrast, the API-level policies will not affect the scope-level policies. But if
there are policies applied at the global-level (through a global policy) for the API, then
those policies will override every other policy configured at the API-level.
The scope-level policies for an API provide a granular enforcement of policies at the
resource-level, method-level, or both for the REST API, or at the operation-level for the
SOAP API.
Note: Scope-level policies are not supported for OData APIs.
An API can have zero or more scope-level policies. When you define the scope-level
policies for an API, keep the following points in minds:
For a policy (for example, Identify and Authorize Application) that can appear only
once in an API, if the same policy is already applied through the API details page,
API Gateway prompts you with a warning message that the scope-level policy takes
precedence over the API-level policy, and is enforced on the API at run-time.
For a policy (for example, Monitor Service Level Agreement) that can appear
multiple times in an API, if the same policy is already applied to the API through
a global policy, API Gateway prompts you with a warning message that the global
policy takes precedence over the scope-level policy, and is enforced on the API at
run-time.
If a resource or method or operation has the same policy (for example, Require
HTTP / HTTPs) applied through different scopes, API Gateway prompts you with
an error message and sets the focus to the conflicting policies. You must remove the
required policy from the individual scope(s) to resolve the conflicts.
API Gateway supports scope-level policies only for the following stages:
M
Odd Header
Policies
Identify and Access

Traffic Monitoring
For information on the usage scenarios of policies configured for the scopes of an API,
see “Example: Usage Scenarios of API Scopes” on page 200.
Creating a Scope-level Policy

You create a policy for the API scope, to enforce the specific set of policies on a collection
of resources, methods, or both, or operations that are associated to the scope. An API can
have zero or more scope-level policies.
To create a scope-level policy

3. Click Edit.
the API is active.
This displays a list of scopes and policies available in the API.
5. In the API Scope box, select the scope for that you want to create a policy.
7. In the expanded list of policies, select the policies that you want to associate with this
scope. To select a policy, click the Add (+) icon next to the policy name. The selected
policies are displayed in the Infographic section.
When you select the policies for the scope-level policy, keep in mind that the policies
shown in the Policy catalog section are determined by the type of the displayed API.
If you do not see a policy that you need, that policy is probably not compatible with
this API.
Use the Delete (X) icon in any individual policy to remove that particular policy from
the Infographic section.
b. In the Policy properties section, set the values for the policy's properties as
necessary.
M
Even Header
Policies
9. Click Open in full-screen to view the policy's properties in full-screen mode.

The Open in full-screen link is located in the upper right-corner of the Policies tab.
10. Set the properties of the displayed policy, and then click OK.
To exit out of full-screen mode, click the Minimize icon.
11. Click Save to create the new scope-level policy.
Click to view the complete list of policies in the updated API.

Viewing List of Scope-level Policies and Policy Details

The Infographic section displays the list of policies that are associated to a selected scope
in the API's Policies tab.
To view the scope-level policies and properties of a policy

4. In the API Scope box, select the scope whose policy details you want to examine.
a. Select the policy whose properties you want to examine.
b. In the Policy properties section, examine the values for the policy's properties as
required.
Examine the properties of the displayed policy, and then click OK.
To exit out of full-screen mode, click the Minimize icon.
7. Click to view the complete list of policies in the updated API.
M
Odd Header
Policies
Modifying Scope-level Policy Details

The API can have a set of policies that are configured globally through a global policy,
or directly through a policy template, or a set of individual policies at the API-level or
scope-level.
To customize the policy configurations at the scope-level, you need to apply the policies
that are available for the API's scope, and then configure the properties of the individual
policies to suit the needs of runtime behavior of that particular API.
You use the Policies tab to examine and modify the properties of a policy at the scope-
level.
To modify the properties of a scope-level policy

3. Click Edit.
the API is active.
5. In the API Scope box, select the scope whose policy details you want to modify.
6. On the Infographic section, modify the policy list and the policy's configuration
8. Modify the properties of the displayed policy, and then click OK.
To exit full-screen mode, click the Minimize icon.
9. When you have completed the required modifications for the scope-level policy,
click Save to save the updated scope-level policy.

M
Even Header
Policies
Deleting a Scope-level Policy

You delete a policy at the scope-level to remove the association between the policy and a
scope.
When deleting a scope-level policy in the API details page, keep the following points in
mind:
When a scope is deleted from the API details, API Gateway removes the policies that
were associated with the deleted scope.
To delete a scope-level policy

3. Click Edit.
the API is active.
A list of scopes and policies available with the API appears.
5. In the API Scope box, select the scope whose policy you want to remove.
6. On the Infographic section, click the x icon in any individual policy to remove that
particular policy from the scope.
7. When you have removed the policy, click Save to save the updated scope-level
policy.

Managing Policy Templates

Important: API Gateway's Standard Edition License does not support policy templates.
You can create and manage policy templates only using the Advanced
Edition License.
Policy templates are a set of policies that can be associated directly with an individual
API. The direct association of the policy template with an API provides the flexibility to
alter the policy's configurations to suit the individual API requirements.
M
Odd Header
Policies
To apply a policy template to an API, modify the details page of the API, and apply the
selected policy template.
Creating a Policy Template

You must have the API Gateway's manage policy templates functional privilege
assigned.
To create a policy template you must perform the following high-level steps:
1. Create a new policy template: During this step, you specify the basic details of the policy
template.
2. Configure the policies: During this step, you associate one or more policies with the
template, and assign values to each of the associated policy's properties.
To create a policy template

2. Click the Policy Templates tab.
A list of all available policy templates appears.
3. In the Policies page, click the Create Policy Template buon.
This opens the Create Policy Template page with the default Policy Details tab.
4. In the Basic Information section, provide the required information for each of the
Field Description
Name Name of the policy template.
Description Description of the policy template.
5. Click Continue to policy configuration.

6. In the Policy Configuration tab, select the policies and configure the properties for each
policy that you want API Gateway to execute when it applies this policy template.
For details, see “Associating Policies with a Policy Template” on page 377 and “
Configuring Properties for a Policy Template” on page 379.
7. Click Save.
Associating Policies with a Policy Template

assigned.
M
Even Header
Policies
The Policy Configuration tab on the Policy Template details page specifies the set of policy
stages and the list of policies (applicable for each stage).
To modify the list of policies of a policy template

3. Select the required template.
The Policy Template details page appears.
4. Click Edit.
5. Click the Policy Configuration tab.
The policy template information is provided in the following sections:
7. In the expanded list of policies, select the policies that you want API Gateway to
execute when it applies this policy template. To select a policy, click the Add (+)
icon next to the policy name. The selected policies are displayed in the Infographic
section.
8. To configure the properties for any new policies that you might have added to the
Infographic section in the preceding steps or to make any necessary updates to the
properties for existing policies in the policy template, see “ Configuring Properties
for a Policy Template” on page 379.
9. When the list of policies is complete and you have configured all of the properties for
the policies correctly, click Save to save the updated policy template.
10. Click to view the complete list of policies in the updated policy
template.
The Overview buon is located in the lower right-corner of the Infographic section. In
addition, you can view the configured properties for the individual policies.
M
Odd Header
Policies
Configuring Properties for a Policy Template

assigned.
The Policy Configuration tab on the Policy Template details page specifies the list of
policies that are applicable for each policy stage in the Policy catalog section. Each policy
in the Infographic section has properties that you must set to configure the policy's
enforcement behavior.
To configure the properties for a policy template

The Policy Template details page appears.
4. Click Edit.
5. Click the Policy Configuration tab.
The policy template information is provided in the following sections:
b. In the Policy catalog section, set the properties as necessary.
8. Click Open in full-screen to view the policy's properties in full screen mode.
The Open in full-screen link is located in the upper right-hand corner of the Policy
Configuration tab. Set the properties of the displayed policy, and then click OK.
To exit full screen mode, click the Minimize icon.
9. After you configure the properties for all of the policies in the Infographic section,
click Save to save the updated policy template.
M
Even Header
Policies
10. Click to view the complete list of policies in the updated policy
template.
Viewing List of Policy Templates and Template Details

The Policy Templates tab displays a list of all available policy templates in API Gateway.
Policy templates are listed alphabetically by name.
In addition to viewing the list of policy templates, you can also examine the details
of a template, create a copy of the template, and delete a policy template in the Policy
Templates tab.
To view the policy template list and properties of a policy template

A lis of all available policy templates appears. This tab provides the following
information about each template:
Column Description
Description The description for the policy template.
You can also perform the following operations on a policy template:

Create a new copy of the policy template.
Delete a policy template to remove it from API Gateway.
3. Select the required policy template.
The Policy Template details page appears. The policy template details are displayed
in the following tabs:
Policy Details: This tab contains a summary of basic information such as the name
and description of the policy template.
M
Odd Header
Policies
Modifying Policy Template Details

assigned.
You use the Policy Template details page to examine and modify the properties of a
policy template.
To modify the properties of a policy template

The Policy Template details page appears. The policy template details are displayed
in the following tabs:
Policy Details: This tab contains a summary of basic information such as name and
description of the policy template.
4. Click Edit.
5. On the Policy Details tab, modify the basic properties of the policy as necessary.
6. On the Policy Configuration tab, modify the policy list and the policy's configuration
7. When you have completed the required modifications on the Policy Template details
page, click Save to save the updated policy template.
If update of a policy template fails, API Gateway displays a pop-up style error
message.
8. Click Overview to view the complete list of policies in the updated policy template.
Deleting a Policy Template

assigned.
You delete a policy template to remove it from API Gateway permanently.
M
Even Header
Policies
To delete a policy template

3. Click the Delete ( ) icon for the required template.
Copying a Policy Template

assigned.
A policy template can become quite complex, especially if it includes many policies.
Instead of creating a new policy template from scratch, it is sometimes easier to copy an
existing template that is similar to the one you need and edit the copy.
When you create a copy of a policy template, be aware that:
When API Gateway creates a copy of a policy template, the new copy of the policy
template is identical to the original one.
There is no expressed relationship between the copy and the original policy (that
is, API Gateway does not establish any type of association between the two policy
templates).
In general, a copied policy template is no different from a policy template that you create
from scratch.
To copy a policy template

3. Click the Copy icon for the required template.
4. In the Copy of Policy Template dialog box, provide the required information for each of
the displayed data fields:
Field Description

API Gateway automatically adds the name of
the existing policy template to the Name field.
You can change the name of the template to
M
Odd Header
Policies
Field Description
suit your needs. But you cannot leave this field
empty.
Description The description for the policy template.
5. Click Copy to save the new policy template.

6. Modify the new policy template as necessary and then save it.
Applying a Policy Template on the API Details Page

You must have the API Gateway's manage APIs functional privilege assigned.
The Policies tab on the API details page specifies the set of policies that API Gateway will
execute when an application requests access to that particular API.
The API can have a set of policies that are applied through a global policy, through a
policy template, through a scope-level policy, and through API-level policies.
To customize the policy configurations for an API using a policy template, you need to
apply the template (containing a set of policies), and then configure the properties of the
individual policies to suit the runtime requirements for that API.
To apply a policy template on the API details page

3. Click Edit.
The API's policy information is provided in the following sections:
Policy stages - Threat Protection, Transport, Identify and Access, Request
Processing, Routing, Traffic Monitoring, Response Processing, Error Handling
5. Click Apply template located in the lower right-corner of the Infographic section.
This opens the Apply template dialog box.
6. In the Template chooser, select one or more policy templates that you want to apply to
the API.
M
Even Header
Policies
You can choose to display the details of an individual policy template by clicking the
Info icon. This option populates the list of policies that are defined in the particular
template.
7. Select one or more policy templates that you want API Gateway to execute at run-
time.
8. Click Next.
You must have at least one template selected to use the Next buon.
9. In the Apply Templates to API wizard, review the list of policies and the configuration
details of the associated policies.
If necessary, you can click Previous to return to the Template chooser wizard and
change your template selections.
If at any time you wish to abandon all your changes and return to the Policies tab,
click Cancel.
10. Click Apply.
If you have one or more policy conflicts, API Gateway displays the conflicting/
incompatible policies with a Conflict icon. You can choose to resolve the policy
conflicts and do a Apply, or simply continue to Apply with conflicts.
If you choose the continue with conflicts, API Gateway sets the focus on the
conflicting policies with Conflict ( ) icon displayed next to the policy names in the
Infographic section and the corresponding policy stages.
API Gateway will redirect you to the Policies tab. The newly applied policy template
comprising a set of policies and the policy properties is displayed in the Infographic
section.
11. After you apply the required policy templates, click Save to save the updated API.
Post-requisites:
Activate the API when you are ready to put it into effect.
Modifying a Policy Template on the API Details Page

assigned.
The Policies tab on the API details page specifies the set of policies that API Gateway
executes when an application requests access to that particular API.
To modify the details of a policy template on the API details page

M
Odd Header
Policies

3. Click Edit.
the API is active.
Policy catalog - Threat Protection, Transport, Identify and Access, Request
b. In the Policy properties section, set the properties as necessary.
c. Use the Delete (X) icon in any individual policy to remove that particular policy
from the Infographic section.
6. Click Open in full-screen to view policy properties in full screen mode.
The Open in full-screen buon is located in the upper right-hand corner of the Policy
Configuration tab.
7. Set the properties of the displayed policy, and then click OK.
To exit full screen mode, click the Minimize icon.
Saving Policy Definition of an API as Policy Template

assigned.
The Policies tab on the API details page specifies the set of policies that API Gateway will
execute when an application requests access to that particular API.
M
Even Header
Policies
You can save the current policy definition of an API as a new policy template. At a later
time, you can reuse this policy template in other APIs. For more information, see “
Applying a Policy Template on the API Details Page” on page 383.
To save policy definition as policy template

Policy catalog - Threat Protection, Transport, Identify and Access, Request
4. Click Save as template located in the lower right-hand corner of the Infographic
section.
5. In the Save as template dialog box, provide the required information for each of the
Field Description
Description Description of the policy template.
6. Click Save.
Supported Alias and Policy Combinations

API Gateway provides a set of aliases whose runtime-specific environment variables can
be used in configuring the policy routing endpoints, routing rules, endpoint connection
properties, and outbound authentication tokens. The types of aliases whose properties
you can use for the policy configurations are:
Simple alias
Endpoint alias
HTTP transport security alias
SOAP message security alias
M
Odd Header
Policies
webMethods IS Service alias

XSLT Transformation alias
Not all policies support the full set of aliases that are available in API Gateway. Some
aliases are applicable only with certain policies and for certain policy parameters. For
example, a Simple alias applies to the routing and traffic monitoring policies, whereas
an Endpoint alias applies only to the routing policies. When you define a Straight
Through Routing policy with a simple alias, the alias property is defined using the
Endpoint URI field. When you define the same Straight Through Routing policy with an
endpoint alias, the alias property is defined using a set of fields - Endpoint URI, SOAP
Optimization Method, HTTP Connection Timeout, Read Timeout, Pass WS-Security
Headers, and Keystore Alias.
The following table identifies the policies and policy parameters that each alias type
supports:
Simple Alias
Policy Name Policy Parameter Name
Straight In the Straight Through Routing definition:

Through
Endpoint URI
Routing
Content-based In the default and custom Route To rule definitions:

Routing
Endpoint URI
Context-based In the default and custom Route To rule definitions:

Routing
Endpoint URI
Load Balancer In the Route To rule definition:

Routing
Endpoint URI
Dynamic In the default and custom Route To rule definitions:

Routing
Endpoint URI
Log Invocation In the Email Destination section:

Email Address
Monitor Service In the Email Destination section:

Performance
Email Address
M
Even Header
Policies
Monitor In the Email Destination section:

Service Level
Email Address
Agreement
Throling In the Email Destination section:

Traffic
Email Address
Optimization
Endpoint Alias
Straight In the Straight Through Routing definition:

Through
Endpoint URI
Routing
SOAP Optimization Method (Applicable only for SOAP
APIs)
HTTP Connection Timeout
Read Timeout
Pass WS-Security Headers (Applicable only for SOAP
APIs)
Keystore Alias
Key Alias
Content-based In the default and custom Route To rule definitions:

Routing
Endpoint URI
APIs)
Read Timeout
APIs)
Keystore Alias
Key Alias
Context-based In the default and custom Route To rule definitions:

Routing
Endpoint URI
M
Odd Header
Policies

APIs)
Read Timeout
APIs)
Keystore Alias
Key Alias
Load Balancer In the Route To rule definition:

Routing
Endpoint URI
APIs)
Read Timeout
APIs)
Keystore Alias
Key Alias
Dynamic In the default and custom Route To rule definitions:

Routing
Endpoint URI
APIs)
Read Timeout
APIs)
Keystore Alias
Key Alias
HTTP Transport Security Alias
M
Even Header
Policies
Outbound In the Authentication scheme:

Authentication -
Alias
Transport
SOAP Message Security Alias (Applicable only for SOAP APIs)
Outbound In the Authentication scheme:

Authentication -
Alias
Message
webMethods IS Service Alias
Invoke webMethods IS Service Alias

webMethods
IS (Request
Processing)
Invoke webMethods IS Service Alias

webMethods
IS (Response
Processing)
XSLT Transformation Alias
Request Transformation Configuration

Transformation
Payload Transformation
(Request
Processing) XSLT Transformation alias
Response Transformation Configuration

Transformation
Payload Transformation
(Response
Processing) XSLT Transformation alias
M
Odd Header
Aliases
6 Aliases
■ Overview ..................................................................................................................................... 392
■ Creating a Simple Alias ............................................................................................................. 392
■ Creating an Endpoint Alias ........................................................................................................ 393
■ Creating an HTTP Transport Security Alias .............................................................................. 394
■ Creating a SOAP Message Security Alias ................................................................................. 398
■ Creating a webMethods Integration Server Service Alias ......................................................... 402
■ Creating an XSLT Transformation Alias .................................................................................... 403
M
Even Header
Aliases
Overview
An alias in API Gateway holds environment-specific property values that can be used in
policy routing configuration. The aliases can be referred to in routing endpoints, routing
rules, endpoint connection properties, and outbound authentication tokens instead of
providing a real value. The corresponding alias value is substituted in place of an alias
name during run-time. Thus the same alias can be referred to in multiple policies and
the change in a particular alias would affect all the policy properties in which it is being
referred. When an API is exported and imported to a different environment, you can
update the alias values specific to the environment instead of updating the policy with
environment specific values. You can create six types of alias:
Simple alias
Endpoint alias
HTTP transport security alias
SOAP message security alias
webMethods IS Service alias
XSLT Transformation alias
Creating a Simple Alias

You must have the API Gateway's manage aliases functional privilege assigned to
perform this task.
A simple alias holds simple key property values. The name of the alias can be used in
the configuration of the properties of a routing policy or an email destination for the
Log Invocation, Monitor Service Level Agreement, Monitor Service Performance, and
Throling Traffic Optimization policies.
To create a simple alias

1. Expand the menu options icon , in the title bar, and select Aliases.
2. Click Create alias.
3. In the Basic information section, provide the following information:
Field Description
Name Name of the alias.
Type Select Simple alias.
M
Odd Header
Aliases
Field Description
Description Description of the alias.
4. Click Technical information and specify a value in the Default value field.
Note: You can specify multiple email addresses, if you are creating an email
alias, for example, abc@gmail.com, test@gmail.com, and so on.
5. Click Save.
Note: If you want to configure this alias in the routing policies, you can follow
the syntax ${aliasname}. For example, if you want to route it to an
endpoint hp/mydevenv.com:7000/api, you can create a simple alias with
the name mystage and its value being hp/mydevenv.com:7000. The
endpoint URL can be specified in the properties as ${mystage}/api.
Creating an Endpoint Alias

perform this task.
An endpoint alias stores the endpoint value along with additional properties such as
connection timeout, read timeout, whether to pass security headers or not, keystore
alias, key alias, and so on.
To create an endpoint alias

Field Description
Type Select Endpoint alias.
4. Click Technical information and provide the following information:
M
Even Header
Aliases
Field Description
Optimization This is applicable only for a SOAP API.

technique
Specify the optimization technique for the SOAP
request received. Select any one of the following:
None. This is the default value. API Gateway does
not use any optimization method to parse the
SOAP requests to the API.
MTOM. Indicates that API Gateway expects to
receive a request with a Message Transmission
Optimization Mechanism (MTOM) aachment and
forwards the aachment to the native service.
SWA. Indicates that API Gateway expects to receive
a SOAP with Aachment (SWA) request and
forwards the aachment to the native service.
Pass WS-Security Passes the security header.

Headers
Endpoint URI Specify the default URI or components of the URI

such as service name.
Connection timeout Specify the time interval (in seconds) after which a
connection aempt times out.
The default value is 30 seconds.
Read timeout Specify the time interval (in seconds) after which a
socket read aempt times out.
Keystore alias Specify the keystore alias of the truststore that

contains all the trusted public certificates.
Key alias Specifies the key alias that is used by the SSL
connection.
5. Click Save.
Creating an HTTP Transport Security Alias

perform this task.
M
Odd Header
Aliases
An HTTP Transport security alias contains transport level security information required
while accessing the native API. Transport level security that are supported in API
Gateway outbound are as follows:
HTTP Basic authentication
OAuth2 authentication
NTLM authentication
Kerberos authentication
To create an HTTP transport secure alias

Field Description
Type Select HTTP transport security alias.
Field Description
Authentication scheme Specify the type of authentication you want to use

while communicating with the native API.
Basic. Uses basic authentication (user name and
password).
Kerberos. Uses Kerberos authentication.
NTLM. Uses NTLM authentication.
OAuth2. Uses OAuth2 authentication.
For the Authentication type Basic, authenticate using the following:
Custom credentials Specifies the values provided in the policy required

to access the native API.
M
Even Header
Aliases
Field Description

Username. Specify a username to access the native
API.
Password. Specify a password to access the native
API.
Domain. Specify a domain to access the native API.
Incoming HTTP basic No properties required. Considers the incoming

auth credentials HTTP basic authentication credentials.
For Authentication type Kerberos, authenticate using any of the following:
Custom credentials Specifies the values provided in the policy required

to obtain the Kerberos token to access the native
API.
Client password. A valid password of the client
LDAP user.
which you want to specify the principal name of
the service that is registered with the principal
database. Select one of the following:
Hostbased. Represents the principal name
using the service name and the host name,
where host name is the host computer.
Delegate incoming Specifies the values provided in the policy required

credentials by the API providers to select whether to delegate
the incoming Kerberos token or act as a normal
client.
M
Odd Header
Aliases
Field Description

LDAP user.
Incoming HTTP basic Specifies the incoming HTTP basic authentication

auth credentials credentials in the transport header of the incoming
request for client principal and client password.
database. Available values are:
Incoming kerberos No properties required. Considers the incoming

credentials kerberos credentials.
For Authentication type NTLM, authenticate using any of the following:
M
Even Header
Aliases
Field Description
Custom credentials Specifies the credentials that are required for the
NTLM handshake.
Username. Name of a consumer who is available in
the Integration Server on which API Gateway is
running.
Password. A valid password of the consumer.
Domain. The domain used by the server to
authenticate the consumer.
Incoming HTTP basic No properties required. Considers the incoming

auth credentials HTTP basic authentication credentials.
Transparent No properties required.
For the Authentication type OAuth2, authenticate using any of the following:
Custom credentials Specifies the OAuth2 token value that would be

added as bearer token in the transport header while
accessing the native API.
Incoming OAuth token Considers the incoming OAuth token to access the
native API.
For Authentication type JWT, authenticate using any of the following:
Incoming JWT Considers the incoming JSON web token to access

the native API.
5. Click Save.
Creating a SOAP Message Security Alias

perform this task.
A SOAP message security alias contains message level security information that is
requires to access the native API. If the native service is enforced with any WS security
policy, API Gateway enforces those policies in the outbound request while accessing the
native API using the configuration parameters specified in the alias.
M
Odd Header
Aliases
To create SOAP message secure alias

Field Description
Type Select SOAP message secure alias.
Field Description
Authentication Specify the type of authentication scheme you want

scheme to use to authenticate the client.
None. Does not use any authentication types to
WSS Username. Generates a WSS username token
and sends it in the soap header to the native API.
Kerberos. Fetches a Kerberos token and sends it to
the native API.
SAML. Fetches a SAML token and sends it to the
native API.
For Authentication scheme None. Does not require any properties.
For Authentication type WSS Username, authenticate using any of the

following:
Custom credentials Specifies the values provided in the policy to be

used to obtain the WSS username token to access the
native API.
M
Even Header
Aliases
Field Description
Username. Specifies a username used to generate the

WSS username token.
Password. Specifies the password used to generate
the WSS username token.
For Authentication type Kerberos, authenticate using any of the following:
Custom Credentials Uses the Basic authentication credentials coming

in the transport header of the incoming request for
client principal and client password.
LDAP user.
Delegate incoming Specifies the values provided in the policy to be used

credentials by the API providers to select whether to delegate
the incoming Kerberos token or act as a normal
client.
LDAP user.
M
Odd Header
Aliases
Field Description

database. Available values are:
Incoming HTTP basic Specifies the incoming HTTP basic authentication

auth credentials credentials to access the native API.
For Authentication type SAML
SAML issuer Specifies the SAML issuer configuration that is used

configuration by the API Gateway to fetch the SAML token which
is then added in the SOAP header and sent to the
native API.
This field is visible and required only if you have
configured a SAML issuer in Administration > Security
> SAML issuer section.
Signing configurations
M
Even Header
Aliases
Field Description
Keystore alias Specify the keystore that needs to be used by API

Gateway while sending the request to the native
API. A keystore is a repository of private key and its
corresponding public certificate.
Key alias The key alias is the private key that is used sign the
request sent to the native API.
Encryption configurations
Truststore alias Select the truststore to be used by API Gateway

when sending the request to the native API.
Truststore is a repository that holds all the trusted
public certificates.
Certificate alias Select the certificate from the truststore that is used
to encrypt the request that is sent to the native API.
5. Click Save.
Creating a webMethods Integration Server Service Alias

perform this task.
A webMethods Integration Server service alias holds the IS service value. The name
of the alias can be used to invoke the Invoke webMethods IS policy for request and
response processing.
To create a webMethods IS service alias

1. Expand the menu options icon , in the title bar, and select User management.
Field Description
Type Select webMethods IS Service alias.
M
Odd Header
Aliases
Field Description
4. Click Technical information and specify the IS service name in the Service name field.
Note: The IS service must be available in the Integration Server, to which the
aliases are deployed.
5. Click Save.
Creating an XSLT Transformation Alias

perform this task.
An XSLT transformation alias holds a list of XSLT style sheets. The name of the alias can
be used in the XSLT Transformation policies for request and response processing.
To create a transformation alias

1. Expand the menu options icon , in the title bar, and select User management.
Field Description
Type Select XSLT Transformation alias.
4. Click Technical information and browse and select an XSLT style sheet in the Select
transformation file field.
5. Click Save.
M
Even Header
M
Odd Header
Applications
7 Applications
■ Overview ..................................................................................................................................... 406
■ Creating an Application .............................................................................................................. 407
■ Viewing List of Applications and Application Details ................................................................. 415
■ Regenerating API Access Key ................................................................................................... 415
■ Modifying Application Details ..................................................................................................... 416
■ Registering an API with Consumer Applications from API Details Page ................................... 416
■ Registering APIs with Consumer Applications from Application Details Page ........................... 417
■ Suspending an Application ........................................................................................................ 418
■ Activating a Suspended Application .......................................................................................... 418
M
Even Header
Applications
Overview
An application defines the precise identifiers by which messages from a particular
application is recognized at run time. The identifiers can be, for example, user name
in HTTP headers, a range of IP addresses, such that API Gateway can identify or
authenticate the applications that are requesting an API.
The ability of API Gateway to relate a message to a specific application enables it to:
Control access to an API at run time (that is, allow only authorized applications to
invoke an API).
Monitor an API for violations of a Service-Level Agreement (SLA) for a specified
application.
Indicate the application to which a logged transaction event belongs.
An application has the following aributes for specifying the identifiers:
IP address, which specifies one or more IP addresses that identify requests from a
particular application. Example: 192.168.0.10
This aribute is queried when the Identify and Authorize Application policy is
configured to identify applications using IP address.
Claims set, which specifies one or more claims that identify requests from a
particular application. The claims are a set of name-value pairs that provide
sufficient information about the application. Example: sub = Administrator.
configured to identify applications using a JWT token or an OpenID token.
Client certificate, which specifies the X.509 certificates that identify requests from a
particular application.
configured to identify the applications by a client certificate.
Identification token, which specifies the host names, user names or other
distinguishing strings that identify requests from a particular application.
This aribute is queried when the Identify and Authorize Application policy action
is configured to identify applications by host name, token, HTTP user name, and
WSS user name.
You can configure various authentication strategies to authenticate an incoming
request to the application. You can create multiple strategies authorized by an API
for an application. These strategies provide multiple authentication mechanisms or
multiple authorization servers for a single authentication scheme. For example, in case
of OAuth authentication scheme, you want the application to support both OKTA and
PINGFederate or OKTA with multiple tenants. This can be configured as OAuth strategy
for the application.
M
Odd Header
Applications
If you have the Manage Application functional privilege assigned, you can create and
manage applications, and register applications with the APIs.
These are the high level stages of managing and using an application:
1. API developers request the API Gateway administrators to create an application for
access as per the required identification criteria.
2. API Gateway provider or administrator validates the request and creates a new
application, there by provisioning the application specific access tokens (API access
key and OAuth credentials).
3. API Developer, upon finding a suitable API, sends a request to API Gateway for
consumption by providing the application details.
4. After validating the request, API Gateway provider or administrator associates the
application with the API. Keys are generated for applications and not for every API
that the application consumes.
Note: The approval process, if any, is handled by the requesting application and
not handled by API Gateway.
5. The API developer can then use the application with the proper identifier (such as
the access key or identifier) to access the API.
API key expiration date
An API Gateway application has an optional expiration date for its API key. When
the API access key expires, the application cannot be identified. The API Gateway
Administrator can configure the apiKeyExpirationPeriod parameter from the General >
Extended settings page. If the expiration date is not specified, then the API key never
expires.
Suspended Applications
You can suspend applications so as to disable the identification of requests temporarily.
If a suspended application is identified while processing a request the request is rejected
with HTTP 403 (Forbidden) error. The response body has the following content:
Application has been identified but it is currently suspended. Please contact
the API Gateway administrator for further details.
You can resume the suspended applications to enable the identification again.
Creating an Application
You must have the API Gateway's manage applications functional privilege assigned to
perform this task.
You can create an application from the Applications page.
M
Even Header
Applications
To create an application
1. Click Applications in the title navigation bar.
2. Click Create application.
Name. Type a name for the application.
Version. Version of the application. By default it is 1.0 but can be modified to a
required value.
Description. Type a description of the application.
Requestor comment.
4. Click Continue to Identifiers >.
Alternatively, you can click Identifiers in the left navigation panel.
You can save the application by clicking Save at this stage and add the Identifiers and
APIs at a later time.
5. Provide the following information in the Identifiers section:
Field Description
IP address range Provide the IP address range or range of trusted

IPv4 or IPv6 addresses that identify requests from a
particular application.
You can add more range options by clicking +Add
and adding the required information.
Partner identifier Specifies the third-party partner's identity.
Client certificates Click Browse and select the client certificate to

be uploaded. The client certificate specifies the
X.509 certificates that requests from a particular
application.
Note: API Gateway supports .cer and .pem certificates

for identifying consumer applications.
You can add multiple certificates by clicking +Add
Claims Provide a set of claims for the JWT and OpenID

clients.
A claim is a unique identifying information that
identify requests from a particular consumer
M
Odd Header
Applications
Field Description
application. The claim set is identified by a unique
Name and is defined as a name-value pair that
consists of a Claim name and a Claim value.
You can add more claims and claims sets by clicking
+Add and adding the required information.
Other identifiers Select one of the options to identify requests from

a particular application and provide the required
value:
Hostname. Specify the host name.
Token. The token that is required to identify
requests from an application.
Username. The username credential to identify
requests from an application.
WS-Security username. The WSS username to
identify requests from an application.
Payload identifier. The payload identifier that is
required to identify requests from an application.
6. Click Continue to APIs >

Alternatively you can click APIs in the left navigation panel.
You can save the application by clicking Save at this stage and add the APIs at a later
time.
7. Type a keyword to find the required API and click +Add to add the API.
Adding an API to the application enables the application to access the API. An API
developer while invoking the API at runtime, has to provide the access token or
identification token for API Gateway to identify the application.
8. Type the required Requestor comment.
9. Click Continue to Advanced >
Alternatively you can click Advanced in the left navigation panel.
You can save the application by clicking Save at this stage and add the APIs at a later
time.
10. Specify the origin from which the responses originating are allowed during response
processing for the application.
11. Click +Add to add the origin.
M
Even Header
Applications
You can add multiple origins using .
12. Click Continue to Authentication >

Alternatively you can click Authentication in the left navigation panel.
You can save the application by clicking Save at this stage and add the
Authentication strategy at a later time.
13. Click Create strategy.
A strategy is a way to authenticate the incoming request and provides multiple
authentication mechanisms or multiple authorization servers for a single
authentication scheme. You can create multiple strategies authorized by an API for
an application.
14. Select one of the Authentication schemes:
OAUTH2. Provide the following information:
Field Description
Name Provide the name for the strategy.
Description Provide a description to describe the strategy.
Authentication Specify the authentication server.

server
The available values are local, which is the
default server or any other configured external
Generate Credentials Enable the toggle buon to generate the client

dynamically in the authorization server and
Type. Select one of the client types:
Confidential. A confidential client is an
application that is capable of keeping a
client password confidential to the world.
This client password is assigned to the
client app by the authorization server. This
password is used to identify the client to
the authorization server, to avoid fraud. An
example of a confidential client could be a
web app, where no one but the administrator
can get access to the server, and see the client
password.
M
Odd Header
Applications
Field Description
Public. A public client is an application that

is not capable of keeping a client password
confidential. For instance, a mobile phone
application or a desktop application that
has the client password embedded inside
it. Such an application could get cracked,
and this could reveal the password. The
same is true for a JavaScript application
running in the users browser. The user could
use a JavaScript debugger to look into the
application, and see the client password.
Application type. Specify the application type.
WEB. A web application is an application
running on a web server. In reality, a web
application typically consists of both a
browser part and a server part. The client
password could be stored on the server. The
password would thus be confidential.
USER_AGENT. A user agent application is for
instance a JavaScript application running
in a browser. The browser is the user agent.
A user agent application may be stored on
a web server, but the application is only
running in the user agent once downloaded.
NATIVE. A native application is for instance
a desktop application or a mobile phone
application. Native applications are
typically installed on the users computer
or device (phone, tablet etc.). Thus, the
client password will be stored on the users
computer or device too.
Token lifetime. Specify the token lifetime in
seconds for which the token is active
Token refresh limit. Specify the number of times
you can use the refresh token to get a new access
token.
Redirect URIs. Specify the URIs that the
authorization server can use to redirect the
resource owner's browser during the grant
process. You can add multiple URIs by clicking
+Add.
M
Even Header
Applications
Field Description
Grant type. Specify the grant type to be used

to generate the credentials. Available options
can be Authorization code, Implicit, Resource
owner, Client credentials, which are dynamically
populated from the authorization server. For
example, if the authorization server does not
support client credentials, the option is not
available in the options list.
Scopes. Select the scopes that are to mapped for
the authentication strategy.
Note:In API Gateway 10.2, the scopes are

automatically created when you associate
an API to an application. From API
Gateway 10.3 onwards you have to select
scopes from the authorization server that
have to be associated with the strategy.
Client id Specify the Client identifier for a client

application available in the authorization server
that identifies the client application in the
authorization server to map the client to the API
Gateway application.
This is required if you have a client application
available in the authorization server and do not want
to dynamically create a client.
JWT. Provide the following information:
Field Description

server
The possible values are local, which is the
M
Odd Header
Applications
Field Description
HMAC algorithm Select if the authorization server is returning

a JWT with HMAC algorithm and provide the
shared secret value to validate the JWT.
OPENID. Provide the following information:
Field Description

server
The available values are local, which is the
Generate Credentials Enable the toggle buon to generate the

credentials required to identify the client
application and provide the following
information:
Type. Select the client type, Public or
Confidential
Confidential. A confidential client is an
application that is capable of keeping a
client password confidential to the world.
This client password is assigned to the
client app by the authorization server. This
password is used to identify the client to
the authorization server, to avoid fraud. An
example of a confidential client could be a
web app, where no one but the administrator
can get access to the server, and see the client
password.
Public. A public client is an application that
is not capable of keeping a client password
confidential. For instance, a mobile phone
application or a desktop application that
has the client password embedded inside
it. Such an application could get cracked,
and this could reveal the password. The
same is true for a JavaScript application
M
Even Header
Applications
Field Description
running in the users browser. The user could
use a JavaScript debugger to look into the
application, and see the client password.
Application type. Specify the application type.
WEB. A web application is an application
running on a web server. In reality, a web
application typically consists of both a
browser part and a server part. The client
password could be stored on the server. The
password would thus be confidential.
USER_AGENT. A user agent application is for
instance a JavaScript application running
in a browser. The browser is the user agent.
A user agent application may be stored on
a web server, but the application is only
running in the user agent once downloaded.
NATIVE. A native application is for instance
a desktop application or a mobile phone
application. Native applications are
typically installed on the users computer
or device (phone, tablet etc.). Thus, the
client password will be stored on the users
computer or device too.
Token lifetime. Specify the token lifetime in
seconds for which the token is active
Token refresh limit. Specify the time in seconds for
which the token refresh is applicable
Redirect URIs. Specify the URIs that the
authorization server can use to redirect the
resource owner's browser during the grant
process. You can add multiple URIs by clicking
+Add.
Grant type. Specify the grant type to be used to
generate the credentials. Available options are
Authorization code, Implicit, Resource owner, Client
credentials.
Scopes. Select the scopes that are to be
associated to the generated client.
Note:In API Gateway 10.2, the scopes are

automatically created when you associate
an API to an application. From API
M
Odd Header
Applications
Field Description
Gateway 10.3 onwards you have to select
scopes from the authorization server that
have to be associated with the strategy.
Client id Specify the Client identifier that identifies the

client application in the authorization server to
map the client to the API Gateway application.
This is required if you do not choose to generate
credentials to identify the client application.
15. Click Add.

The strategy is configured and listed in the Strategies table.
16. Click Save.
The application is created and listed in the list of applications in the Manage
applications page, once approved.
Viewing List of Applications and Application Details

You can view the list of applications in the Manage applications page from where you
can create, delete, and select an application to view its details.
To view the application list and application details

A list of all registered applications is displayed.
2. Select an application.
The application details page displays the following information: basic information
that contains details such as name, description, owner, and creation time, identifiers,
access tokens, APIs registered for the application, advanced configurations, and
authentication strategies configured for the application.
Regenerating API Access Key

You must have the API Gateway's manage applications functional privilege assigned to
perform this task.
You can regenerate an API access key in the Application details page from where you
can view application details.
M
Even Header
Applications
To regenerate an API key

A list of all registered applications is displayed.
The application details page displays the basic information, identifiers, access tokens,
API key, APIs registered and strategies configured for that application.
3. Click .
The API access key is regenerated and the new API access key appears in the API
access key field.
Modifying Application Details

You can modify the details of an application as required from the application details
page.
To modify application details

A list of registered applications is displayed.
3. Click Edit in the application details page.
4. Modify the required fields in the Basic information section.
5. Click Identifiers.
6. Modify the required fields in the Identifiers section.
7. Click APIs.
8. Add or delete the APIs that are registered.
9. Modify the strategies or create a new strategy.
10. Modify the required values.
11. Click Save.
Registering an API with Consumer Applications from API

Details Page
Consumer applications created in API Gateway can be associated with APIs from the
API details page.
M
Odd Header
Applications
To register APIs with consumer applications

A list of APIs is displayed.
2. Select an API.
3. Click Edit in the API details page.
4. Click Application tab in the API details page.
5. Type characters in the search field and click the Search icon.
This displays the list of applications starting with the characters that you provide.
6. Select the required applications and click +.
You can add more applications in a similar way.
7. Click Save.
Registering APIs with Consumer Applications from

Application Details Page
Consumer applications created in API Gateway can be associated with the APIs from the
application details page.
To register APIs with consumer applications

A list of registered applications is displayed.
3. Click Edit in the application details page.
4. Click APIs in the left navigation panel.
5. Type characters in the search field and click the Search icon.
This displays the APIs starting with the characters that you have typed in.
6. Select the required API and click +.
You can add more APIs in a similar way.
7. Click Save.
M
Even Header
Applications
Suspending an Application
You must have the API Gateway's manage applications functional privilege assigned or
you must be the owner of the application to perform this task.
You can suspend an application from the Applications details page.
To suspend an application
A list of all the available applications are displayed.
2. Click the toggle buon (Active state), in the action column for the respective
application, to suspend the application.
Alternatively, you can click Suspend in the application details page.
The application is suspended. The toggle buon in the Applications page changes
to (suspended state) and the option in the application details page changes to
Suspend.
Activating a Suspended Application

You must have the API Gateway's manage applications functional privilege assigned or
you must be the owner of the application to perform this task.
You can activate a suspended application, from the Applications details page, which
enables the identification again.
To activate a suspended application

A list of all the available applications are displayed.
2. Click the toggle buon (suspended state), in the action column for the
respective application, to activate the application.
Alternatively, you can click Activate in the application details page.
The application resumes. The toggle buon in the Applications page changes to
(active state) and the option in the application details page changes to Suspend.
M
Odd Header
API Packages and Plans
8 API Packages and Plans

■ Overview ..................................................................................................................................... 420
■ Creating a Package ................................................................................................................... 420
■ Creating a Plan .......................................................................................................................... 421
■ Viewing List of Packages and Package Details ........................................................................ 424
■ Modifying a Package .................................................................................................................. 425
■ Deleting a Package .................................................................................................................... 426
■ Activating a Package ................................................................................................................. 426
■ Publishing a Package ................................................................................................................ 427
■ Viewing List of Plans and Plan Details ...................................................................................... 427
■ Modifying a Plan ........................................................................................................................ 428
■ Deleting a Plan ........................................................................................................................... 429
M
Even Header
Overview
An API Package refers to a logical grouping of multiple APIs from a single API provider.
A package can contain one or more APIs and an API can belong to more than one
package. You must have the API Gateway's manage packages and plans functional
privilege assigned to manage API packages and plans.
An API Plan is the contract proposal presented to consumers who are about to subscribe
to APIs. Plans are offered as tiered offerings with varying availability guarantees, SLAs
or cost structures associated with them. An API package can be associated with multiple
plans at a time. This helps the API providers in providing tiered access to their APIs to
allow different service levels and pricing plans. Though you can edit or delete a plan
that has subscribers, Software AG recommends you not to do so.
Note: Package and plan subscriptions can be done only through API Portal.
You can create packages and plans, associate a plan with a package, associate APIs with
a package, view the list of packages, package details, and APIs and plans associated with
the package in the API Gateway user interface.
Creating a Package
You must have the API Gateway's manage packages and plans functional privilege
You can create an API Package from the Manage packages and plans page.
To create an API Package

1. Click Packages in the title navigation bar.
2. Click Create in the Manage packages and plans section.
3. Select Package.
4. Click Create.
Field Description
Name Name of the API package.
Version Version assigned for the API package.
Description A brief description for the API package.
M
Odd Header
Field Description
Icon An icon that is displayed for the API package.

Click Browse and select the required image to
be displayed as the icon for the API package.
The icon size should not be more than 100 KB.
You can save the API package at this point and add the plans at a later time.
6. Click Continue to add plans.
Alternatively, click Plans in the left navigation pane.
7. Select the plans that are to be associated with the API package.
You can save the API package at this point and add APIs at a later time.
8. Click Continue to add APIs.
Alternatively, click APIs in the left navigation pane.
9. Type characters in the search box and click the search icon to search for the required
APIs.
A list of APIs that contain the characters specified in the search box appears.
10. Select the required APIs to be associated with the Package and click + to add them.
You can delete the APIs from the package by clicking the Delete icon adjacent to the
API in the API list.
11. Click Save.
Creating a Plan
You can create a Plan from the Manage packages and plans page.
To create a plan
2. Click Create in the Manage packages and plans section.
3. Select Plan.
4. Click Create.
M
Even Header
Field Description
Name Name of the plan.
Version Version assigned for the plan.
Description A brief description for the plan.
Icon An icon that is displayed for the plan.

Click Browse and select the required image to be
displayed as the icon for the plan. The icon size
should not be more than 100 KB.
You can save the plan at this point and add the pricing and traffic optimization
configurations at a later time.
6. Click Continue to Pricing.
Alternatively, click Pricing in the left navigation pane.
7. Provide the following information in the Pricing section:
Field Description
Cost Specifies the cost for the plan.
Terms Specifies the terms of conditions for the pricing.
License Specifies the license information.
You can save the plan at this point and provide traffic optimization configurations at
a later time.
8. Click Continue to Quality of Service.
Alternatively, click Rate limits in the left navigation pane.
9. Click + Add Rule.
10. Provide the following information in the Create Rule section:
Field Description
Maximum request count Specifies the maximum number of requests

handled.
Value provided should be an integer.
M
Odd Header
Field Description
Interval Specifies the value for the interval for which the
maximum request count is handled.
Interval unit Specifies the unit of measurement of the time

interval.
For example: minutes, seconds, and so on
Violation message Specifies the text that displays when the rule is
violated.
11. Click Ok.

This creates the rule and displays it in the Configured rules table. Click + Add rule to
add more rules. You can edit or delete the rules by clicking the Edit and the Delete
icons respectively.
At a later time, when this plan is applied to an API through a package, the rules that
you configured for this plan are enforced on the applied API.
12. Click Quota and provide the following information in the Quota seings section.
Field Description
Maximum request quota Specifies the maximum number of requests

handled.
Block on breach When selected it specifies that the access to the

API is blocked when there is a rule violation.
By default, this option is not selected.
Interval Specifies the value for the interval for which the
maximum request quota is handled.
Interval unit Specifies the unit of measurement of the interval.

Example: minutes, seconds, and so on
Violation message Specifies the text that displays when the policy is
violated.
M
Even Header
Field Description
Notification settings Specifies whether notifications are to be sent on

rule violations.
Enable the toggle buon to enable the
notifications and provide the following
information:
Notify after (in %): Provide a value which is a
number. A notification is sent to the configured
email IDs once the total request count reaches
the % value as provided in the maximum quota
value.
Violation message: Provide the content of the mail
that is sent to the configured email Ids once the
quota request count reaches the limit specified.
Email Ids: Provide email Id of the recipient
to which notifications have to be sent of
notification once the quota request count
reaches the limit specified. Click . You
can add multiple recipients.
Note:The SMTP seings under Administrator

seings > Destinations has to be provided
for email to be sent.
Send Digital Events: Sends the monitor events

to the DES destination once the quota request
count reaches the limit specified.
Note:The Digital events seings has to be set

under Administrator seings > Destination
Note: The number of requests within a Quota interval is retained in case of

server crash or restart. For example, if the number of requests against a
Quota is 10 and if the server restarts or crashes, the number of requests for
that Quota is retained when the server is up.
13. Click Save.

The plan is created and listed in the list of plans.
Viewing List of Packages and Package Details

You can view the list of packages in the Packages section of the Manage packages and
plans page from where you can create, delete, and select a package to view its details.
M
Odd Header
To view the package list and package details

A list of all packages appears. You can perform various operations like activating a
package, publishing or unpublishing a package, and deleting a package.
2. Select a package.
The basic information, and the associated plans and APIs for the selected package
appears in the package details page.
Modifying a Package
You must have the API Gateway's manage packages and plans assigned to perform this
task.
You can modify the basic information, include or exclude plans and APIs of the package.
You can modify a package only if it is in inactive state.
To modify a package
A list of all packages appears.
2. Select a package.
The basic information, and the associated plans and APIs for the selected package
appear on the package details page.
3. Click Edit.
The package details appear.
Note: The Edit option is available only if the package is in inactive state.
4. You can modify the information related to the package, as required, in the Basic
information section.
5. Click Plans in case you want to modify the plans associated with the package.
A list of plans associated with the package and list of available plans appears.
6. You can do the following:
Add more plans to the package by selecting plans listed in the available plans
list.
Delete the plans from the package by clearing the check box of the plan
associated with the package.
7. Click APIs in case you want to modify the APIs associated with the package.
M
Even Header
A list of APIs associated with the package and a search box to search for APIs that
need to be added to the package appear.
Add more APIs to the package. You can search for APIs using the search box and
click + adjacent to the API to add it
Delete the APIs from the package by clicking the Delete icon adjacent to the API
in the APIs list.
9. Click Save.
This saves the modified package.
Deleting a Package
You must have the API Gateway's manage packages and plans assigned to perform this
task.
You can delete a package from the Package list that appears on the Manage packages
and plans page. You can not delete a package if it is in active state. You have to
deactivate it before deleting it.
To delete a package
2. Click the Delete icon for the package that has to be deleted.
Activating a Package
You must have the API Gateway's activate/deactivate packages assigned to perform this
task.
You can activate a package so that a consumer can try out APIs in the package with the
package level token. When the consumer requests a token from API Portal, the request is
processed in API Gateway and a token is sent back to API Portal. This token is visible to
the consumer on the Access Token page. The consumer can test the APIs in the package
with this token on the API Try out page.
To activate a package
A list of all packages appears with their status as Inactive or Active.
2. Click the activation toggle buon for the package.
M
Odd Header
The package is now activated.

Alternatively you can click Activate on the Packages details page to activate the
package.
Publishing a Package
You must have the API Gateway's publish to API Portal functional privilege assigned to
perform this task.
You can publish a package to the configured destination, for example API Portal.
Once the package is published, the APIs associated with the package are available
to consumers. The package level token is applicable to all APIs associated with the
package. The consumers do not have to request an access token for individual APIs to
consume them.
Ensure the following before publishing a package:
A destination is configured.
The package is active.
The package has at least one plan and API associated with it.
The APIs associated with the package is published to the destination.
To publish a package
2. Click the Publish icon for the package that has to be published.
A success messages is displayed when the package is successfully published.
The package is now published to the destination, for example API Portal, that is
configured and is available on API Portal to consumers.
You can unpublish a package once it is published by clicking the Unpublish icon for the
required package.
Viewing List of Plans and Plan Details

You can view the list of plans in the Plans section of the Manage packages and plans
page from where you can create, delete, and select a plan to view its details.
To view the plan list and plan details

2. Click Plans.
M
Even Header
A list of all plans appears. You can deleting a plan by clicking the Delete icon for the
respective plan.
3. Select a plan.
The basic information, the pricing, and Quality of service associated with the
selected plan appears in the plan details page.
Modifying a Plan
You can modify a plan to change the pricing details and Quality of service associated
with the plan.
To modify a plan
2. Click Plans.
A list of all plans appears.
3. Select a plan.
The plan details page displays the basic information, pricing details, and the Quality
of service associated with the plan.
4. Click Edit.
The plan details appear with fields that you can edit.
5. You can modify the information related to the plan, as required, in the Basic
information section.
6. Click Pricing in case you want to modify the pricing model associated with the plan.
7. Modify the pricing plan as required.
8. Click Rate limits if you want to modify the rules associated with the plan.
A list of rules associated with the plan appears.
Add more rules to the plan. Click Add rule to create and add rules to the plan.
Modify the already configured rule. Click the Edit icon for the rule listed in the
Configured rules list and modify the details as required.
Delete rules from the plan. Click the Delete icon adjacent to the rule in the
Configured rules list.
M
Odd Header
10. Click Quota settings if you want to modify the quota seings for the plan.
11. Modify the quota seings as required.
12. Click Save.
This saves the modified plan.
Deleting a Plan
You can delete a plan from the Plans list that appears in the Plans section of the Manage
packages and plans page. You can delete a plan only if it is not associated with a
package. You have to disassociate the plan with the package before deleting it.
To delete a plan
2. Click Plans.
A list of plans appears.
3. Click the Delete icon for the plan that has to be deleted.
M
Even Header
M
Odd Header
Import Archives
9 Import Archives
■ Importing Exported Files ............................................................................................................ 432
M
Even Header
Import Archives
Importing Exported Files

You can import already exported archives of APIs, global policies, and other related
assets and re-create them in API Gateway. For more information about exporting APIs,
see “Exporting APIs” on page 209. For information about exporting global policies, see
“Exporting Global Policies” on page 369.
Each artifact in an archive is associated with a universally unique identifier (UUID)
across all API Gateway installations. When importing an archive, the UUID helps in
determining whether the corresponding artifact is already available in API Gateway. In
such a situation, you can specify whether to overwrite an already existing artifact during
the import process.
Note: Imported APIs, applications, policies, and aliases become visible in API
Gateway immediately.
Active APIs are replaced during import with the updated API and the API
level policies.
The updated APIs and updated API level policies do not become effective
for ongoing requests.
Active APIs are replaced during deployment with zero downtime without
breaking ongoing requests.
Imported applications become effective immediately, even the ongoing
requests are affected.
Imported aliases and global policies do not affect ongoing requests.
You must have the API Gateway's import assets functional privilege assigned to import
an archive.
Note: During export or import of assets, ensure that the master password is
identical across stages and on different instances of API Gateway.
To import the exported files

1. Expand the menu options icon , in the title bar, and select Import.
Select archive file Click Browse to select a file or ZIP format

file.
Advanced options Select this option to overwrite either or all

the following with the imported content:
M
Odd Header
Import Archives
API
Policy
Applications
Alias
Note: API Gateway supports backward compatibility for API Gateway 10.1
version or higher when importing the archives of APIs. If you want to use
the archives of API Gateway 10.2 in versions 10.3 and higher, you must
export them from API Gateway 10.2 fix 3 or higher.
3. Click Import.
The Import report displays the following information:
Type The artifact type. The available values are:

API
Policy
Policy Actions
Applications
Alias
Successful The number of successful imports for

each artifact type.
Unsuccessful The number of unsuccessful imports for

each artifact type.
Replaced The number of instances replaced for each

artifact type.
Warning The number of warnings displayed

during the import of each artifact type.
API Gateway displays warning messages
when the import is successful but some
additional information is required.
4. Click Download the detail report here > to download the detail report.
M
Even Header
Import Archives
The detail report displays the following information about the imported artifact:
Name The name of the artifact imported.
Type The artifact type. The available values

are:
API
Policy
Policy Actions
Application
Alias
Status The status of the imported artifact. The

Success
Replaced
Warning
Failure
Explanation The reason if the import fails or if a

warning occurs.
M
Odd Header
Asset Promotions
10 Asset Promotions
■ Manage Stages, Promotions, and Rollbacks ............................................................................. 436
M
Even Header
Asset Promotions
Manage Stages, Promotions, and Rollbacks

API Gateway supports staging and promotion of assets. In a typical enterprise-level,
solutions are separated according to the different stages of Software Development
Lifecycle (SDLC) such as development, quality assurance (QA), and production stages.
As each organization builds APIs for easy consumption and monetization, continuous
integration (CI) and continuous delivery (CD) is an integral part of the solution. CI is a
development practice that requires developers to integrate code into a shared repository
several times a day, and CD is a software engineering approach in which teams produce
software in short cycles, ensuring that the software can be reliably released at any time.
API Gateway provides the staging and promotion feature to automate the CI and CD
practices. Modifications made to the APIs, policies, and other assets can be efficiently
delivered to the application developers with speed and agility.
Staging and promotion allows you to:
Promote all the run time assets across different stages. The supported assets are:
APIs
Global policies
Policy templates
Applications
Aliases
Packages
Plans
Administrative configurations - Load balancer, Extended seings, API fault,
Keystore and Truststore seings, and Custom Assertions.
To promote any of the administrative configuration, must make sure that the
corresponding administrative seings are already configured in API Gateway.
Threat protection rules
Select and promote a subset of assets from one stage to another stage. For example,
you can promote a single API and its dependencies from one stage to another.
Optionally select the asset's dependencies during the promotion.
Create stage-specific aliases.
When promoting an alias from source stage to target stage, API Gateway checks if
the target stage already has an alias. If so, then API Gateway replaces the existing
alias in target stage with the alias that is promoted from source stage.
Note: Stage-specific alias is supported only for simple alias and endpoint alias.
M
Odd Header
Asset Promotions
Roll back assets in case of incomplete information.

Repromote assets, if there are any recent changes, to the already promoted stages.
Stages
The fundamental phases of assets starts with requirements or needs at the development
stage and once the assets are developed, they are promoted to the QA stage for testing,
after testing of the assets is complete, the assets are promoted to the production stage.
An asset's overall lifecycle can be split across two or more API Gateway instances. For
example, assets that are in the development and test phases of their lifecycle can be
maintained in one instance and assets that are deployed (that is, in production) can be
maintained in a separate instance.
When the asset's lifecycle is split across multiple API Gateway instances, each
participating instance is referred to as a stage. A stage definition in API Gateway
describes an API Gateway instance by its name and configuration information.
Note: Software AG recommends you to have API Gateway instances across stages to
be completely independent. For example, the API Gateway instances from the
Development stage and the API Gateway instances from the QA stage must
not share any resources in common such as databases.
Adding a Stage
Pre-requisites:
You must have the Manage promotions functional privilege assigned to perform this
task.
API Gateway can contain one or more stages. You define a stage to represent the asset's
lifecycle such as development, test, and production.
To add a stage
1. Expand the menu options icon , in the title bar, and select Promotion management.
2. Click Add Stage.
Field Description
Name Mandatory. Name of the stage.
Note: A stage name must be unique within API Gateway.
Description Description of the stage.
M
Even Header
Asset Promotions
4. Provide the following information in the Technical information section:
Field Description
Stage URL Mandatory. The URL of the host machine where the stage
is deployed on an API Gateway installation.
The Stage URL value is specified in the format,
<scheme>://<host>:<port>. The scheme is http or
https. The host is the host name of the machine on
which the target API Gateway instance is running. The
port is the port number of the target API Gateway
instance.
Username Mandatory. The username of a registered API Gateway

user who has the Manage promotions or Manage assets
functional privilege in the target API Gateway instance.
Password Mandatory. A valid password of the API Gateway user

identified by the aribute Username.
Keystore alias The alias of the keystore containing the private key that
is used for performing asset promotion from one (source)
stage to another (target) stage.
The Keystore alias field contains a list of the available
keystore aliases in API Gateway. If there are no
configured keystore aliases, this field lists the default
Integration Server keystore, DEFAULT_IS_KEYSTORE .
Note: This field is required when the Stage URL scheme is

set to https.
Key alias The alias of the private key that is stored in the keystore
(signing) specified by the keystore alias.
The Key alias field contains a list of the available aliases in
the selected keystore. If there are no configured keystores,
this field is empty.
Note: This field is required when the Stage URL scheme is

set to https.
5. Click Save.
M
Odd Header
Asset Promotions
Viewing Stage List and Stage Details

The Stages tab displays a list of the available stages in API Gateway.
In addition to viewing the list of stages, you can also examine the details of a stage and
delete a stage in the Stages tab.
To view the stage list and stage details

The Stages tab displays a list of available stages.
This tab provides the following information about each stage:
Column Description
Name Name of the stage.
Description The description for the stage.
2. Click the required stage whose details you want to examine.

The Stage details page appears. The stage details are displayed in the following
sections:
Basic information: This section contains the stage name and description.
Technical information: This section contains the stage specific URL, authentication
credentials to access the stage, and the keystore configurations.
Modifying Stage Details

Pre-requisites:
task.
You can modify the basic or the technical information of a stage at any time.
To modify the stage details

2. Click the required stage whose details you want to modify.
The Stage details page appears.
3. Click Edit.
This opens the basic information of the stage.
M
Even Header
Asset Promotions
4. Modify the basic information as required.

5. Click Technical information.
This opens the technical information of the stage.
6. Modify the technical information as required.
7. Click Save.
Deleting a Stage
Pre-requisites:
task.
You delete a stage to remove it from API Gateway permanently. You can remove a stage
at any time.
To delete a stage
2. Click the Delete icon for the stage that you want to delete.
Promotions
Promotion refers to moving API Gateway assets from the source stage to one or more
target stages. For example, you might want to promote assets you have developed on
servers in a Development stage (the source API Gateway instance) to servers in a QA or
Production stage (the target API Gateway instance).
When you promote an asset from one stage to another, the asset's metadata is copied
from the source instance to the target instance.
Promoting Assets
Pre-requisites:
task.
Promoting assets from one (source) stage to another (target) stage includes the following
high-level steps:
1. Select assets for promotion: During this step, you search for assets by using a keyword
and by performing a type search that sorts and filters the results.
M
Odd Header
Asset Promotions
Search using a keyword: You can search for all assets whose string aributes (asset
name, description, and so on) contain a certain keyword (character string).
Search using a Type: You can search for assets on the basis of types.
You may use the Search by type filter to restrict the types on which the search
is conducted. In the Search by type panel, API Gateway shows you a list of
supported asset types.
2. Optionally select assets' dependencies for promotion: During this step, you specify
whether the dependencies (for example, a list of applications that are registered for
an API, subscriptions for a package, and so on) of the selected assets will be included
for the promotion.
3. Select the stages to promote: During this step, you specify one or more target stages to
which you want to promote the selected assets and their dependencies.
4. Configure the promotion details: During this step, you provide the promotion-specific
information.
Important: If you plan to perform bulk promotion of assets from a source stage
to a target stage, Software AG recommends you to increase the value
of the pg.gateway.elasticsearch.http.socketTimeout property, located in
SAG_Root/IntegrationServer/instances/IS_Instance_Name/packages/
WmAPIGateway/config/resources/elasticsearch/config.properties.
The default value of this property is 3000. To bulk promote assets, for
example, 50 numbers, you would set the value of this property to 60000.
Depending on the number of assets you want to promote, increment the
value as 70000, 80000, and so on.
You must restart API Gateway for changes to this property to take effect.
To promote assets
2. Select Promotions.
The Search page appears.
3. Click Promote.
4. In the Search by keyword text box, type the keyword to search for assets. You can use
one or more wildcards to specify the keywords.
API Gateway returns the assets that match the specified keyword.
5. In the Search by type drop-down list, select the required type(s). Select the All check
box to search across all asset types.
API Gateway returns the assets that match the selected type(s). The number of search
results is displayed in the results area, for example, Showing 10 results. If no
results are found, the results area is displays a blank page.
M
Even Header
Asset Promotions
6. Optional. Select the Include admin configurations check box if you want to include
administrative configurations in the promotion.
API Gateway displays the administrative configurations that are supported for
promotion. The available options are:
Load balancer
Extended settings
API fault
Custom assertions
Keystore/Truststore
Important: Before you configure API Gateway to promote an administrative

configuration, make sure that the corresponding administrative seings
are already configured in API Gateway. For example, to include the Load
balancer configuration in the asset promotion set, the required Load
balancer URLs should be configured.
7. Select the assets and the administrative configurations that you want to promote.
8. Click Next.
The Assets and dependencies page appears.
9. Select the referenced assets that you want to promote.
10. Click Next.
The Stages page appears.
11. Select the target stages to that you want to promote the assets, dependencies, and
administrative configurations.
12. Click Next.
The Promote page appears.
Field Description
Name Mandatory. Name of the promotion.
Description Description of the promotion.
Note: The Overwrite assets if exists on selected stages option allows you to
overwrite assets that exist on the target stages. If you do not want to
overwrite assets in the target stages, clear this check box.
14. Click Promote.
M
Odd Header
Asset Promotions
The selected assets, dependencies, and administrative configurations are promoted

to the selected stages.
The Stage-specific promotion status page displays the status of the asset promotion
in each of the selected stages. The available values are:
Success
Failure
The page also displays the reason if the promotion fails.
Viewing Promotion List and Promotion Details

The Promotions tab displays a list of the available asset promotions in API Gateway. The
asset promotions are listed alphabetically by name.
In addition, you can examine the details of an asset promotion history, repromote assets
to the configured stages, and delete the promotion history from API Gateway database
in the Promotions tab.
To view the promotion list and promotion details

The Promotions tab displays a list of available asset promotions.
This tab provides the following information about each promotion:
Column Description
Name Name of the stage.
Promoted by Name of the user who initiated the asset

promotion.
Promotion time The time at which the asset promotion occurred.
Status The status report on the asset promotion.
3. Examine the Report link in the Status column and check for any errors that occurred
during the asset promotion.
The Promotion status report displays the following information:
M
Even Header
Asset Promotions
Column Description
Asset type Name of the asset type that was promoted from
the source instance.
Name Name of the asset that was promoted from the

source instance.
Status The status of the asset promotion.
Comments A descriptive comment on the asset promotion

status.
4. Click the required promotion whose details you want to examine.

Repromoting Assets
Pre-requisites:
task.
If you have made recent changes to an asset's information, you can repromote the
updated asset to the already promoted target stages.
If you need to update an asset, for example, you need to correct an aribute seing,
modify the asset's description, that has already been promoted to a target stage, you can
simply make the change directly to the asset in the source target and then repromote the
updated asset to the target stage just as you did with the previous version of the asset. In
a multi-stage environment, you will need to repromote the updated assets in each of the
participating API Gateway instances.
To repromote assets
The Promotions tab displays a list of available promotion histories in API Gateway.
3. Click the Repromote icon for the required assets' promotion history.
The Stages page appears.
4. Select the target stages to that you want to repromote the assets, dependencies, and
administrative configurations.
5. Click Next.
M
Odd Header
Asset Promotions

Field Description
Name Mandatory. Name of the promotion.
Description Description of the promotion.
Note: The Overwrite assets if exists on selected stages option allows you to
overwrite assets that exist on the target stages. If you do not want to
overwrite assets in the target stages, clear this check box.
7. Click Promote.
The selected assets, dependencies, and administrative configurations are repromoted
to the selected stages.
The Stage-specific promotion status page displays the status of the asset repromotion
in each of the selected stages. The available values are:
Success
Failure
The page also displays the reason if the repromotion fails.
Rollbacks
Rollback is the process of restoring the asset's metadata in the target API Gateway
instance to a previous state.
You might need to rollback assets to revert any promotional data changes being made in
the target API Gateway instance.
Rollback Asset Promotions

Pre-requisites:
task.
You can rollback an asset promotion that is already available in the target stage at any
time.
To rollback asset promotion

2. Select Rollbacks.
M
Even Header
Asset Promotions
The Rollbacks tab displays a list of available promotion histories.

3. Click the Rollback icon for the promotion history that you want to rollback.
Viewing Rollback List and Rollback Details

The Rollbacks tab displays a list of the available asset promotion rollbacks in API
Gateway. The rollbacks are listed alphabetically by name.
In addition, you can also examine the details of a rollback, and delete the rollback
history in the Rollbacks tab.
To view the rollback list and rollback details

2. Select Rollbacks.
The Rollbacks tab displays a list of available asset promotion rollbacks.
This tab provides the following information about each rollback:
Column Description
Name Name of the rollback.
Promotion time The time at which the asset promotion was

rolled back.
Status The status report on the rollback operation.
3. Examine the Report link in the Status column and check for any errors that occurred
during the rollback process.
The Promotion status report displays the following information:
Column Description
Asset Type Name of the asset type that was promoted from
the source instance.
Asset Name Name of the asset that was promoted from the
source instance.
M
Odd Header
API Gateway Analytics
11 API Gateway Analytics

■ Analytics Dashboards ................................................................................................................. 448
■ Viewing API Usage Report ........................................................................................................ 456
■ Downloading API Usage Report ................................................................................................ 457
■ Runtime Events and Metrics Data Model .................................................................................. 458
M
Even Header
Analytics Dashboards
The analytics dashboards display a variety of charts to provide an overview of API
Gateway performance and its API usage. The data for these dashboards come from the
API Gateway destination store. In API Gateway there are two types of dashboards. Each
of these dashboards has various filters that can be applied as per the required metrics to
be monitored.
API Gateway dashboard. Displays API Gateway-wide analytics such as Summary of
APIs, API usage, API trends, the top performing API and the non-performing API
analytics, audit logs, applications and package related event information. This can
be accessed by expanding the menu options icon , in the title bar, and selecting
Analytics.
API-specific dashboard. Displays API specific analytics such as API invocation
trends by response time, success and failure rates, API performance, consumer or
application traffic for a specific API. This can be accessed from the API details page.
The dashboard displays depend on the events and metrics generated in API Gateway
and their types. An event is a kind of notification or alert generated by the API Gateway
Metrics and Event Notification module. Various types of event are generated based on
the behavior of the transactions in the system. Events generated by API Gateway are real
time events made persistent in the store and sent to configured destinations.
These are the types of events generated in API Gateway:
Transactional event : Provides a summary of each runtime transaction in the system.
It is generated when a Log Invocation policy is included for the API. For example,
if an API has the policy aached to it, then for every invoke the system generates
a transaction event. API Gateway provides a system global policy, Transaction
logging, which are pre-configured in the product. This policy is, by default,
deactivated. The transaction logging policy has standard filters and a log invocation
policy that logs request or response payloads to a specified destination.
Error event: Provides details of an error that occurred during an API invoke. This
event is generated whenever there is an error in the system during a runtime service
invocation. This is configured as part of destination configuration.
Monitoring event: Provides a summary of event details along with the breach
information when there is a threshold breach in any of the configured parameters.
Monitoring could be done based on various parameters such as Total Request Count,
Total Success Count, Response Time, and Availability. Monitoring can be done at the
consumer application level too so that each consumer can be tracked individually.
These events are generated when a Monitor Service performance and Monitor SLA
Policy is included for the API.
Policy violation event: Provides a summary of the policy violations that occurred in the
system. When a policy aached to an API is violated, the system generates the policy
violation event for alerting the provider. The Identity and Access, Authorization,
M
Odd Header
and Schema Validation policies generate these events. This is configured as part of
destination configuration.
Lifecycle event: Provides a summary of the life cycle of the API Gateway instance.
Whenever the instance is started or stopped, a life cycle notification is generated.
This is configured as part of destination configuration.
Threat protection event: Provides a summary of the threat protection filter and rule
violations. When a filter or rule is violated, the system generates the threat protection
violation event. This is configured a part of destination configuration.
Note: Internalization is not supported in API Gateway dashboards.
API Gateway Dashboard

You can view the API Gateway dashboard by expanding the menu options icon ,
in the title bar, and selecting Analytics. The dashboard displays the API Gateway-wide
analytics based on the metrics monitored.
You can select the time interval from the drop-down options, and click Apply filter to filter
the analytics based on the time interval chosen.
If you select Custom, you can type the From Date and To Date to specify the time interval
in which you want to view the API Gateway-wide analytics.
You can click on the specific event in the list under Legend to view the specific event in
any of the widgets. You can view additional details for an event by hovering the cursor
over a particular color in the graphical representations.
In the Applications dashboard, you can filter the data using the filter for Applications in
the specified time interval. The Applications drop-down list displays all the applications.
When you select an application, its data is displayed. By default, the data displayed is
for all the applications.
In the Packages dashboard, you can filter the data using the filter for Packages in the
specified time interval. The Packages drop-down list displays all the packages. When
you select a package, its data are displayed. By default, the data displayed is for all the
packages.
In the Audit logs dashboard, you can filter the data using the filter for Audit logs in the
specified time interval. It displays the data of all the auditable events.
In the API usage details dashboard, you can filter the data using the filter for the API
invocations in the specified time interval (in years). By default, the data displayed is
for all the API invocations. This dashboard is visible only when API Gateway uses
a transaction-based licensing model when each API invocation is considered as a
transaction and API Gateway keeps a track of these transactions.
Note: The Summary, Trends, and Application analytics are visible only in API
Gateway Full Edition. Threat protection analytics is the only data visible in
API Gateway Firewall Edition. The threat protection analytics information is
visible only if you select the Alert type as flow service in Policies > Global threat
M
Even Header
protection > Alert settings section. The threat protection analytics information is
visible only if you select the Alert type as flow service in Policies > Global threat
protection > Alert settings section.
Category Metric Description
Summary Overall events Displays a pie chart that lists different

events being monitored and each of
these event categories is depicted with
different colors.
Application activity Displays the application activity in API

Gateway during the specified time.
Runtime events Displays the run time event details

such as time when the event was
generated, API Name, the application
that generated the event, event type,
description of the alert generated due
to the event, status, and the source of
event.
Payload size Displays the payload size of the

request and responses during data
transfer in the specified time.
This data is picked up from the
transactional event that is triggered
when a log invocation policy is applied
to the API.
Package performance Displays a pie chart depicting package

performance during the specified time.
The different colours in the pie chart
depict different packages this API
belongs to.
Trends Events over time Displays the trending of events

generated by the APIs across API
Gateway over time.
API trend by success Displays the trending of APIs based on

their success rate in the performance
metrics.
M
Odd Header
API trend by failure Displays the trending of APIs based

on their failure rate in the performance
metrics.
Overall error trends Displays a graph depicting the

performance of all the APIs in the
system based on the error event
generated. Each of these event
categories is depicted with different
colors.
Applications Events per application Displays a pie chart that depicts the
activity of events per application being
monitored and each of these categories
is depicted with different colors.
Violations per Displays the number of violations

application per application based on the events
generated such as monitoring, SLA
violation, and policy violations.
Activity rate of This bar chart displays the package

consumed packages that the selected application has
consumed (when an application is
chosen in the filter).
Hover the cursor over the bar chart
to see the number of invocations
to the package using the specified
application.
Activity rate for Displays the activity rate for all

consumed APIs the APIs that are consumed by the
application during the specified time.
Runtime events Displays the run time event details

such as API Name, event type, date
when the event was created, the agent
on which the event was generated,
description of the alert generated due
to the event, the source of event, and
the application that generated the
event.
M
Even Header
Packages Package invocations Displays the number of package

invocations during the specified time.
Trending subscription Displays the trending subscriptions for

for package the package based on the number of
invocations.
The different colours in the donut pie
chart depict the trending behavior
of the different applications in the
package.
Trending APIs in the Displays the number of invocations

package for an API for an application for the
selected package over the specified
time interval.
Threat Threat protection Displays the graphical representation

protection filters of the events based on the filter
violations during the specified time.
Threat protection rules Displays the graphical representation

of the events based on the rule
violations during the specified time.
Threat protection Displays the threat protection event

events details such as Time, filter name, rule
name, resource path, server host, and
request time.
Audit logs Time Displays the time the event occurred.
User Displays the name of the user who

caused the event.
Status Displays the current status of the

transaction. The available values are:
SUCCESS
FAILURE
Source machine Displays the host name of the machine

on which the event occurred.
M
Odd Header
Object type Displays the type of API Gateway

object on which the event occurred.
ACCESS_PROFILE_MANAGEMENT
ALIAS_MANAGEMENT
ANALYTICS_MANAGEMENT
API_MANAGEMENT
APPLICATION_MANAGEMENT
APPROVALS_MANAGEMENT
GROUPS_MANAGEMENT
PACKAGE_MANAGEMENT
PLAN_MANAGEMENT
PROMOTION_MANAGEMENT
POLICY_MANAGEMENT
USER_MANAGEMENT
Object Displays the UUID that uniquely

identifies the object in the database.
Message Displays the success message or error

message as a result of the event.
Client IP address Displays the IP address of the machine

on which the event occurred.
Action Displays the type of action for the

event. The available values are:
LOGIN
LOGOUT
CREATE
UPDATE
DELETE
ACTIVATE
DEACTIVATE
M
Even Header
Payload Displays the content of data payload

for the event.
API usage API Gateway This bar chart displays the trending of
details invocation usage API invocations across API Gateway.
Hover the cursor over the bar chart to
see the number of API invocations for
the current month.
API Gateway Displays the details of the number of

invocation usage API invocations for each month.
details
API usage details Displays the API invocation details

for each API such as API Name, API
usage for each month and year.
API-specific Dashboard
You can view the API-specific dashboard by navigating to the API details page and
clicking the Analytics icon for the specific API. The dashboard displays the following
analytics based on the metrics monitored.
You can select the time interval and click Apply filter to filter the analytics based on the
time interval chosen. You can select the time interval from the drop-down options.
If you select custom, you can type the From date and To date to specify the time interval
for which you want to view the API-specific analytics.
For the specified time interval you can also filter based on an API. The API drop-down
list displays all the APIs. On selecting an API, the data displayed is for the selected API.
You can click on the specific event in the list under Legend to view the specific event in
any of the widgets. You can view additional details for an event by hovering the cursor
over a particular color in the graphical representations.
Metric Description
Events over time Displays the trending of events generated by the

selected API over time.
API invocations Displays the number of time the API was invoked
during the specified time.
M
Odd Header
Metric Description
API invocation pattern Displays API invocation over period of time

during the specified time interval in the form of a
line graph.
Native service performance Displays information on how fast the native

service responds to the request received in
the specified time based on the data in the
transactional event.
Response code trend Displays the trend based on the response codes
received from various events for the API during
the specified time.
API trend by response Displays the trending of the selected API based
on the response time from the performance
metrics for that API.
Success vs Failure Displays the trending of API based on its

success rate as compared to its failure rate in the
performance metrics for the specified time.
Runtime events Displays the run time event details for the
selected API. Displays information on the event
type, date when the event was created, the agent
on which the event was generated, description of
the alert generated, the source of event, and the
application that generated the event.
Service result cache Displays a bar graph showing the number of

responses served from cache and the number of
responses fetched from the native service at the
operation level for the selected API during the
specified time.
Method level invocations Displays the method level invocations per

operation for the API during the specified time.
You can hover the cursor over the stacked bar
chart to view the various methods invoked per
operation or resource and also the operations
or resources for the selected API during the
specified time.
M
Even Header
Viewing API Usage Report

You must have the manage user administration functional privilege to view and
download the API usage details. You can view the API usage that is stage-specific or
across stages.
The API usage report shows the transaction usage across all stages. When you click
on the API usage details > Report, it loads the transaction usage across all stages for the
current month. You can then specify a filter range or view stage specific transaction
usages and also download these as PDF or CSV reports.
To view an API usage report

2. Click API usage details > Report.
3. You can view the API detail report for transaction counts for APIs in Global
aggregation as follows:
a. Click All stages.
b. Select a month in the From month field.
The table lists the transaction counts for the APIs across all stages from the
month selected in the From month field to 12 months from the selected month
or the current month, whichever is less. For example, if the current month is
April 2018 and you select Jan 2018, then the report is shown for the period from
Jan 2018 to Apr 2018. If you select Feb 2017, then the report is displayed for the
period from Feb 2017 to Jan 2018 (12 month range from the selected month). You
can download this report either in the PDF format or a CSV format.
4. You can view the API detail report for transaction counts for APIs in a single stage as
follows:
a. Click Current stage.
The table lists the transaction counts for the APIsin the current stage from the
month selected in the From month field to 12 months from the selected month
or the current month, whichever is less. For example, if the current month is
April 2018 and you select Jan 2018, then the report is shown for the period from
Jan 2018 to Apr 2018. If you select Feb 2017, then the report is displayed for the
period from Feb 2017 to Jan 2018 (12 month range from the selected month).You
can download this report either in the PDF format or a CSV format.
M
Odd Header
Downloading API Usage Report

You must have the manage user administration functional privilege to view and
download the API usage details. You can view the API usage that is stage-specific or
across stages.
To download an API usage report

2. Click API usage details > Report.
3. You can download the API detail report for transaction counts for APIs in All stages
as follows:
a. Click All stages.
The table lists the transaction counts for the APIs in All stages from the selected
month to the current month.
c. Click Download as PDF report to download the report in the PDF format. The PDF
report has the details such as API name, version and the API usage per month
globally across stages.
d. Click Download as CSV report to download the report in the CSV format. The CSV
globally across stages.
4. You can download the API detail report for transaction counts for APIs in a single
stage as follows:
a. Click the single stage instance box.
The table lists the transaction counts for the APIs in the single stage from the
selected month to the current month.
c. Click Download as PDF report to download the report in the PDF format. The PDF
globally in the selected stage.
d. Click Download as CSV report to download the report in the CSV format. The CSV
report has the details such as API name, version and the API usage per month in
the selected stage.
M
Even Header
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 The average amount of time it took the API to complete all
Time invocations in the current interval. This is measured from
M
Odd Header
Metric Reports on...

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 The maximum amount of time it took the API to complete

Response Time an invocation in the current interval.
Minimum The minimum amount of time it took the API to complete

Response Time an invocation in the current interval.
Successful Request The number of successful API invocations in the current

Count interval.
Total Request The total number of requests for each API running in API
Count 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
API Portal
Audit Log
CentraSite
Elasticsearch
Email
Local Log
API Gateway
The runtime events and metrics payload is generated by API Gateway at run-time. The
columns that make up the events and metrics data model for API Gateway are listed
below:
Transactional Events
Column Description
apiId The unique identifier for the API.
M
Even Header
Column Description
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.
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
M
Odd Header
Column Description
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
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.
pacakgeId The unique identifier for the API package.

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
M
Even Header
Column Description
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,
M
Odd Header
Column Description
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"}
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


Example: SampleAPI

Example: 1.0

the API invocation.
applicationIp IP address of the application associated with the API

invocation.
M
Even Header
Column Description
Example: 10.20.248.33

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

Example: Error Event

Example: GET


Example: 200
M
Odd Header
Column Description
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.
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


Example: SampleAPI

Example: 1.0

the API invocation.

invocation.
Example: 10.20.248.33

invocation.
M
Even Header
Column Description

Gateway.
Example: 1501671101509


Example: Monitor Event

Example: GET


Example: 200

M
Odd Header
Lifecycle Events
Column Description
Gateway.
Example: 1501671101509

Example: LifeCycle
gatewayStatus Status of the API Gateway instance.

Possible values are: STARTED or STOPPED
Policy Violation Events
Column Description

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

Example: PolicyViolation


Example: SampleAPI
M
Even Header
Column Description

Example: 1.0

the API invocation.

invocation.
Example: 10.20.248.33

invocation.
Gateway.
Example: 1501671101509


Example: Policy Violation Event
httpMethod The HTTP method used to request the API access.

Example: GET

M
Odd Header
Column Description

Example: 200

Performance Metrics
Column Description


Example: SampleAPI

Example: 1.0
availability The percentage of time that an API was available during

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
Gateway.
M
Even Header
Column Description
Example: 1501671101509

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

interval.
Example: 10

successCount The number of successful API invocations in the current

interval.
M
Odd Header
Column Description
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 submied.
Example: 10.60.34.152
requestTime Date and time the request was submied.

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.
M
Even Header
Column Description
Example: invoke/pub.date/getCurrentDate

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
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:
Column Description


Example: SampleAPI

Example: 1.0
consumerId The unique identifier for the consumer associated with

the API invocation.
M
Odd Header
Column Description
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
correlationID The unique identifier that is automatically generated for

to query the log.
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


M
Even Header
Column Description

Example: 20
queryParameters This is applicable only for REST APIs. Query

request The API request payload data.

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: 200
responseHeaders Response header in the outgoing response.
M
Odd Header
Column Description
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"}



payloads in bytes.
Example: 100

Example: 120
Error Events
Column Description


Example: SampleAPI
M
Even Header
Column Description

Example: 1.0

the API invocation.

invocation.
Example: 10.20.248.33

invocation.
Gateway.
Example: 1501671101509

Service invocation for SampleAPI was rejected based on policy
violation, response code: 503



M
Odd Header
Column Description
Example: 503

Monitoring Events
Column Description


Example: sla


Example: SampleAPI

Example: 1.0

the API invocation.

invocation.
Example: 10.20.248.33
M
Even Header
Column Description

invocation.
Gateway.
Example: 1501671101509

Example: Monitor Event

Example: GET


Example: 200

M
Odd Header
Lifecycle Events
Column Description
Gateway.
Example: 1501671101509
eventStatus Status of the API Gateway instance.


Example: LifeCycle
targetName Name of the API Gateway instance reporting the event.

Column Description


alert message.


M
Even Header
Column Description

Example: SampleAPI

Example: 1.0

the API invocation.

invocation.
Example: 10.20.248.33

invocation.
Gateway.
Example: 1501671101509



M
Odd Header
Column Description
Example: 200

Performance Metrics
Column Description


Example: SampleAPI

Example: 1.0

100.
Example: 100

caller.
Example: 135
Gateway.
Example: 1501671101509
M
Even Header
Column Description

Example: Performance Metrics Event

interval.
Example: 10

examine metrics.
Example: 2015-08-26 04:13:35 PM
examine metrics.
Example: 2015-08-26 04:13:45 PM

interval.
Example: 343

interval.
Example: 10


interval.
Example: 100
M
Odd Header
Column Description

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 submied.
Example: 10.60.34.152
requestTime Date and time the request was submied.

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
M
Even Header
Column Description

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
published to the configured Audit Log destination. The columns that make up the events
and metrics data model for Audit Log are listed below:
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 wrien to the log.
Example: 2017-08-07 07:22:22
M
Odd Header
Column Description
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.
policy that is configured for the API.
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
EVENT_PK The primary key (PK) that uniquely identifies the event
that occurred.
Example: 1
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
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

M
Even Header
Column Description
Example: 1336
ROOTCONTEXTID The unique identifier for the root context information

API Gateway uses to connect related entries from
different logs.
Example: 81546147-41a8-4998-8150-02ba67bb08c2
SERVERID The API Gateway server on which the transaction event

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

Example: 6dfcd849198c4a7e96b4ff89bc2deaf5
STATUS Status of the API request.

TOTAL_TIME Time in milliseconds required to invoke the API

Example: 1042
M
Odd Header
CentraSite
published to the configured CentraSite destination. The columns that make up the
events and metrics data model for CentraSite are listed below:
Column Description
ApiUserVersion The system-assigned version identifier for the API.

Example: 1.0
Consumer Name of the consumer associated with the API

invocation.
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
Created Time Date and time when the event was generated in API
Gateway.
Example: 2017-08-09 01:27:45 AM
Event Type The type of event that occurred.

Example: Transaction Event
PartnerId The unique identifier for the partner that generated the
audit record.
Example: unknown
M
Even Header
Column Description
Provider Round Trip Time in milliseconds required for API Gateway to

Time invoke a native provider and receive a response. This
Example: 1700
RequestPayload The API request payload data.

ResponsePayload The API response payload data.

Total Round Trip time Time in milliseconds required to invoke the API
Example: 1707
Gateway Name of the API Gateway instance reporting the event.

Request Status Status of the API request.

Error Events
Column Description

Example: 1.0

invocation.
M
Odd Header
Column Description


the API invocation.
Example: be8b27d6-8f79-4c6e-b06c-a628d2ba30c3

invocation.
Example: 10.60.20.169
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


Monitoring Events
Column Description

Example: 1.0
M
Even Header
Column Description
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

Example: MSLA_ALERT MESSAGE

invocation.
Example: SUCRQ_App

the API invocation.
Example: d0e2e008-1890-4f2c-8a91-7678cb92dbfb

invocation.
Example: 10.60.37.118
Gateway.
Example: 2017-08-08 02:27:34 PM

Example: Monitoring Event
Error Description Message that describes the error that occurred.

Example: Resource / not found
M
Odd Header
Column Description

Monitored Attribute The monitored aribute which has breached the

configured SLA.
Example: AVGRESPONSETIME GT 1.0, SUCCESSCOUNT EQ
3, REQUESTCOUNT GT 10
Column Description

Example: 1.0
Alert Source Name of the API Gateway policy that generated the
alert message.
Alert Type The type of alert generated for the event.

Alert Description Text of the alert message sent to a configured

Example: A violation of policy was detected : Unable to
identify the application for the request

invocation.
Example: unknown

the API invocation.
M
Even Header
Column Description
Example: unknown

invocation.
Example: 10.60.37.118
Gateway.
Example: 2017-08-09 08:25:52 AM


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.

LifeCycleStatus Status of the API Gateway instance.

LifeCycleAlertDescription The alert notification message for the lifecycle event.

Example: Alert_Message
M
Odd Header
Elasticsearch
published to the configured Elasticsearch destination. The columns that make up the
events and metrics data model for Elasticsearch are listed below:
Column Description

Example: af70b2de-c9c5-4f40-94be-7d8622743e42

Example: SampleAPI

Example: 1.0

the API invocation.

invocation.
Example: 10.60.37.42

invocation.
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
M
Even Header
Column Description
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.
Gateway.
Example: 1501671101509


Example: GET

packageId The unique identifier for the API package.

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

M
Odd Header
Column Description
Example: 1367
queryParameteres This is applicable only for REST APIs. Query

reqPayload The API request payload data.

resPayload The API response payload data.


Example: 404


payloads in bytes.
Example: 51

Example: 1401
Error Events
Column Description
M
Even Header
Column Description

Example: SampleAPI

Example: 1.0

the API invocation.

invocation.
Example: 10.60.37.42

invocation.
Gateway.
Example: 1501671101509

Example: Native service provider error. Code : 404


Example: Error
M
Odd Header
Column Description
Example: GET


Example: 404
Monitoring Events
Column Description


alert message.
Example: Monitorpolicy

Example: Monitor


Example: SampleAPI

Example: 1.0

the API invocation.
M
Even Header
Column Description

invocation.
Example: 10.60.37.42

invocation.
Gateway.
Example: 1501671101509


Example: Monitor

Example: GET
monitorAttr The monitored aribute which has breached the

configured SLA.


Example: 200
M
Odd Header
Column Description


alert message.



Example: SampleAPI

Example: 1.0

the API invocation.
Example: 9434e90d-65c3-4e37-8ccb-595b8df3e645

invocation.
Example: 10.60.37.42

invocation.
M
Even Header
Column Description

Gateway.
Example: 1501671101509



Example: GET


Example: 503
Performance Metrics
Column Description


Example: SampleAPI
M
Odd Header
Column Description
Example: 1.0

100.
Example: 100.0

caller.
Example: 1376
Gateway.
Example: 1501671101509

Example: PerformanceData

interval.
Example: 1

examine metrics.
Example: 02 Aug 2017 10:51:31 GMT
examine metrics.
Example: 02 Aug 2017 10:52:31 GMT
M
Even Header
Column Description

interval.
Example: 1401

interval.
Example: 1352


interval.
Example: 1

Example: 2
Email
published to the configured Email destination. The columns that make up the events and
metrics data model for Email are listed below:
Column Description
API Name of the API in which the event occurred.

Example: SampleAPI
Description Message that describes the date and time the API was
invoked and the application associated with the API
invocation.
M
Odd Header
Column Description
Invoked at 4/24/18 1:50 PM Consumer Name: Unknown

Consumer ID: Unknown
Native Endpoint The endpoint URL of the native API being invoked.
Operation/Resource Name of the operation or resource that is being invoked

Name on the API.
Runtime Policy Name of the runtime policy that is enforced on the API.
Example: Log Invocation
Status Status of the API invocation.

Version The system-assigned version identifier for the API.

Example: 1.0
Monitoring Events
Column Description

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

Example: Test
Attribute The monitored aribute which has breached the

configured SLA.
M
Even Header
Column Description

Consumer ID The unique identifier for the consumer associated with

the API invocation.
Consumer Name Name of the consumer associated with the API

invocation.
Native Endpoint The endpoint URL of the native API that is being
invoked.
Operation/Resource Name of the operation or resource that is being invoked

Name on the API.
Runtime Policy Name of the runtime policy that is enforced on the API.
Version The system-assigned version identifier for the API.

Example: 1.0
Local Log
published to the configured Local Log destination. The columns that make up the events
and metrics data model for Local Log are listed below:
M
Odd Header
Column Description

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 IP address of the application associated with the API

Address invocation.
Example: 10.60.37.42
Application Name Name of the application associated with the API

invocation.
Correlation ID The unique identifier that is automatically generated for

to query the log.
Error origin The origin of error.

Example: Nativeservice
Invoked at Date and time the API is invoked.

Example: Invoked at 5/14/18 6:56 PM
Operation/Resource Name of the API operation or resource that is invoked.

name
Example: /pet
M
Even Header
Column Description
Partner ID The unique identifier for the partner that generated the
audit record.
Example: unknown
Runtime Policy Name of the API Gateway policy that triggered the
event.
Session Id A string the API Gateway server generates to uniquely

Example: 81439d366e874bc79d9f81490e30e6e0
Status Status of the API request.

Target endpoint The endpoint URL of the native API that is invoked.
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 aribute which has breached the

configured SLA.
3, REQUESTCOUNT EQ 1
Description Message that describes the event that occurred.
M
Odd Header
Column Description
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.
Operation/Resource Name of the API operation or resource that is invoked.

name
Example: /pet
Policy name Name of the API Gateway policy that triggered the
event.
Example: Monitor Policy

Webmethod API

Uploaded by

Document Informationclick to expand document informationwebmethod API

Document Informationclick to expand document information

Copyright:

Available Formats

Webmethod API

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Webmethod API

Uploaded by

Copyright:

Available Formats

webMethods API Cloud: API Gateway User's Guide

Document ID: YAIC-UG-103-20190111

About this Guide............................................................................................................................11

webMethods API Gateway............................................................................................................ 15

API Gateway Administration.........................................................................................................21

webMethods API Cloud: API Gateway User's Guide Version 10.3 3

Configuring Truststore Information.............................................................................60

webMethods API Cloud: API Gateway User's Guide Version 10.3 4

Adding a Service Registry...............................................................................................124

Users and Access Profiles......................................................................................................... 129

webMethods API Cloud: API Gateway User's Guide Version 10.3 5

Activating SOAP to Rest Transformation........................................................................ 187

webMethods API Cloud: API Gateway User's Guide Version 10.3 6

Request Transformation........................................................................................... 262

webMethods API Cloud: API Gateway User's Guide Version 10.3 7

Managing Scope-level Policies...............................................................................................372

API Packages and Plans.............................................................................................................419

webMethods API Cloud: API Gateway User's Guide Version 10.3 8

Asset Promotions........................................................................................................................ 435

API Gateway Analytics................................................................................................................447

webMethods API Cloud: API Gateway User's Guide Version 10.3 9

webMethods API Cloud: API Gateway User's Guide Version 10.3 10

About this Guide

Bold Identiﬁes elements on a screen.

Narrowfont Identiﬁes service names and locations in the format

| Separates two mutually exclusive choices in a syntax line. Type

[] Indicates one or more options. Type only the information inside

webMethods API Cloud: API Gateway User's Guide Version 10.3 11

Online Information and Support

Software AG Empower Product Support Website

webMethods API Cloud: API Gateway User's Guide Version 10.3 12

webMethods API Cloud: API Gateway User's Guide Version 10.3 13

webMethods API Cloud: API Gateway User's Guide Version 10.3 14

1 webMethods API Gateway

webMethods API Cloud: API Gateway User's Guide Version 10.3 15

Introduction to webMethods API Gateway

API Gateway provides the following key features:

webMethods API Cloud: API Gateway User's Guide Version 10.3 16

Searching Data in API Gateway

webMethods API Cloud: API Gateway User's Guide Version 10.3 17

webMethods API Cloud: API Gateway User's Guide Version 10.3 18

Using Help in API Gateway

webMethods API Cloud: API Gateway User's Guide Version 10.3 19

webMethods API Cloud: API Gateway User's Guide Version 10.3 20

2 API Gateway Administration

webMethods API Cloud: API Gateway User's Guide Version 10.3 21

Overview of Administration Tasks

Configuring Extended Settings

webMethods API Cloud: API Gateway User's Guide Version 10.3 22

To configure the extended settings

Parameter and Description

The default value is true.

.dll - Windows dynamic link library

.exe - Executable program

webMethods API Cloud: API Gateway User's Guide Version 10.3 23

Parameter and Description

The default value is false.