0% found this document useful (0 votes)
6 views

API Gateway Getting Started

The document provides a comprehensive guide on getting started with webMethods API Gateway version 11.1, covering installation, configuration, and management of APIs. It details deployment methods using Docker and the IBM Installer, as well as steps to create and test REST, SOAP, and GraphQL APIs. Additionally, it outlines features such as API security, policy enforcement, and analytics, along with troubleshooting tips for deployment issues.

Uploaded by

fermyno
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
6 views

API Gateway Getting Started

The document provides a comprehensive guide on getting started with webMethods API Gateway version 11.1, covering installation, configuration, and management of APIs. It details deployment methods using Docker and the IBM Installer, as well as steps to create and test REST, SOAP, and GraphQL APIs. Additionally, it outlines features such as API security, policy enforcement, and analytics, along with troubleshooting tips for deployment issues.

Uploaded by

fermyno
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 122

webMethods API Gateway Getting Started

Version 11.1

September 2024
Copyright Super iPaaS Integration LLC, an IBM Company 2024
Document ID: YAI-GS-111-20241220
Table of Contents

About this Documentation.......................................................................................................................5


Document Conventions.....................................................................................................................6

1 What is API Gateway?............................................................................................................................7

2 Deployment............................................................................................................................................11
How to install API Gateway using Docker?.................................................................................12
How Do I Install API Gateway using IBM Installer?..................................................................17
Connecting to Elasticsearch Database and Kibana......................................................................20
Launching and logging on to API Gateway.................................................................................21
Troubleshooting Tips: Starting and configuring Elasticsearch and Kibana.............................21

3 Create your first REST API.................................................................................................................23


Creating a REST API by importing an API from a file...............................................................24
Creating a REST API by importing an API from a URL.............................................................26
Testing a REST API...........................................................................................................................28

4 Create your first SOAP API................................................................................................................31


Creating a SOAP API by importing an API from a file..............................................................32
Creating a SOAP API by importing an API from a URL............................................................35
Testing a SOAP API using SOAPUI..............................................................................................37
Testing a SOAP API using curl.......................................................................................................39

5 Create your first GraphQL API..........................................................................................................41


Creating a GraphQL API by Importing an API from URL........................................................42
Creating a GraphQL API by Importing an API from a File.......................................................44
Testing a GraphQL API using Postman........................................................................................45

6 Publish an API to Developer Portal..................................................................................................49

7 Monitor your API..................................................................................................................................53

8 Debug an API.........................................................................................................................................63

9 API Mocking..........................................................................................................................................69

10 Authenticate your API........................................................................................................................75

11 Rate limit your APIs...........................................................................................................................83

webMethods API Gateway Getting Started 11.1 iii


Table of Contents

Configuring rate limiting for an API.............................................................................................86


Testing the ratelimit API..................................................................................................................88

12 API Transaction Logging...................................................................................................................91

13 Request and Response Transformation..........................................................................................95


Use case 1: E-Commerce API Request Header Transformation................................................96
Use case 2: Response Message Transformation...........................................................................99
Testing Request and Response Transformation Policies...........................................................101

14 Global Policies...................................................................................................................................105

15 Routing Policies.................................................................................................................................109

16 Validate API Specification...............................................................................................................115

iv webMethods API Gateway Getting Started 11.1


About this Documentation
■ Document Conventions .................................................................................................... 6

webMethods API Gateway Getting Started 11.1 5


This documentation describes how you can install, and configure API Gateway and other API
Gateway components to effectively manage APIs for services that you want to expose to consumers,
whether inside your organization or outside to partners and third parties.

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 font Identifies:

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.

... Indicates that you can type multiple options of the same type. Type only the
information. Do not type the ellipsis (...).

6 webMethods API Gateway Getting Started 11.1


1 What is API Gateway?
IBM 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 Developer Portal for external facing
developers' consumption. API Gateway supports REST-based APIs, SOAP-based APIs, WebSocket
APIs, OData APIs and GraphQL APIs, provides protection from malicious attacks, provides a
complete run-time governance of APIs, and information about gateway-specific events and
API-specific events.

API Gateway features


API Gateway provides these key features:

Support for different types of APIs

API Gateway supports REST-based APIs, SOAP-based APIs, WebSocket APIs, OData APIs,
and GraphQL 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 attacks 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 blocklisting
specified IP addresses, detecting and filtering requests coming from particular mobile devices.

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
webMethods API Gateway Getting Started 11.1 7
1 What is API Gateway?

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

API Gateway provides routing policies such as content-based, and conditional routing, 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 or post-process the request or response messages.

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.

Functional privileges

API Gateway allows you to assign functional privileges to a user or group (LDAP or local)
using teams. The functional privileges are grouped together to form an team, which is associated
to a group. You must have a functional privilege assigned to perform any of the key API
Gateway features.

API Mashups

8 webMethods API Gateway Getting Started 11.1


1 What is API Gateway?

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.

webMethods API Gateway Getting Started 11.1 9


1 What is API Gateway?

10 webMethods API Gateway Getting Started 11.1


2 Deployment
■ How to install API Gateway using Docker? .................................................................... 12

■ How Do I Install API Gateway using IBM Installer? ........................................................ 17

■ Connecting to Elasticsearch Database and Kibana ....................................................... 20

■ Launching and logging on to API Gateway .................................................................... 21

■ Troubleshooting Tips: Starting and configuring Elasticsearch and Kibana ..................... 21

webMethods API Gateway Getting Started 11.1 11


2 Deployment

There are different ways of deploying API Gateway. You can deploy stand-alone API Gateway
instance either using Docker image or using IBM webMethods Installer. The deployment can be
in containers and on virtual machines. In the following sections you would learn how to install
API Gateway using Docker and IBM webMethods Installer.

How to install API Gateway using Docker?


Why Docker?

Applications often fail to run correctly when moved from one environment to another due to
differences in configurations, underlying library requirements, and other dependencies. To enable
developers and IT professionals to deploy applications seamlessly across environments, software
development technologies increasingly use a technique called containerization.

Containers solve this problem by providing lightweight, immutable deployment and packaging
infrastructure. Docker is one such containerization framework that can be used to create and run
API Gateway as containers. API Gateway container bundles together the code of the application
along with the configuration files, libraries, and dependencies required for API Gateway to run.
Containerized applications can be tested individually and deployed as container image instances
to the host operating system. By this means, developers and IT professionals can deploy API
Gateway across environments with little or no modification.

You can run API Gateway in containers or on Virtual machines. Running API Gateway in containers
is favourable as the containers can be orchestrated with container orchestration platforms like
Kubernetes. To facilitate running API Gateway in a Docker container, IBM provides API Gateway
images in the MyIBM Container Software Library.

IBM offers a Docker image for API Gateway that includes both the API Gateway server and its
UI. Containers using this image must be composed with separate external Elasticsearch and external
Kibana instances, both version 8.12.2. API Gateway will not start unless it is connected to a running
Elasticsearch instance.

This article explains how to run an API Gateway container, apigw and start using API Gateway.

Before you begin

Ensure that you have installed the latest version of Docker.

Ensure that the docker host provides at least 4 GB of main memory. To accommodate the space
for Elasticsearch, set the virtual memory kernel setting to 262144 by running the following
command on your Docker host:
sysctl -w vm.max_map_count=262144

Complete the following steps to download certified container images from IBM Entitled
Registry:

1. Ensure that you have obtained the entitlement key.

2. Log in to MyIBM Container Software Library with the IBM ID and Password that are
associated with the entitled software. In case, you are not directed to the entitlement page,
click Get an entitlement key and obtain the entitlement key.

12 webMethods API Gateway Getting Started 11.1


2 Deployment

3. In the Entitlement key section, click Copy key to copy the entitlement key to the clipboard.

4. Save the entitlement key to a safe location for later use.

5. Open Command Prompt.

6. Log in to Docker using the docker login command.

A sample docker login command is as follows:


docker login cp.icr.io -u cp -p entitlement_key

Replace entitlement_key with the actual entitlement key that you obtained from the MyIBM
Container Software Library. This key grants access to entitled container images.

7. Download the certified container image using the docker pull command.

A sample docker pull command to download the API Gateway image is as follows:
docker pull cp.icr.io/cp/webmethods/api/image-name:tag

Replace image-name with the actual name of the Docker image you want to pull. For
example, if you are pulling the API Gateway image, you might use api-gateway.

Replace tag with the specific version (or tag) of the image you want. For example, use
a version like 11.x to pull that specific version of the image.

To install API Gateway using Docker

1. Run the API Gateway container image by composing it with an Elasticsearch container and a
Kibana container. Start the Elasticsearch instance or container using the following command:
docker network create apigw
docker run --name elastic-svc
--net apigw -d -p 9200:9200 -p 9300:9300 -e "xpack.security.enabled=false"
-e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:8.12.2

The container starts within the apigw network.

2. Once the Elasticsearch container is available, start the API Gateway container using the
following command:
docker run -d -p 5555:5555 -p 9072:9072 \
-v
${PWD}/meteringConfiguration.xml:/opt/softwareag/common/metering/conf/meteringConfiguration.xml
--env apigw_elasticsearch_hosts=elastic-svc:9200 \
--env apigw_kibana_dashboardInstance=http://kibana-svc:5601 \
--hostname apigw-svc \
--net apigw \
--name apigw cp.icr.io/cp/webmethods/api/api-gateway:11.x

where:

5555 and 9072 is the HTTP port of Integration Server and API Gateway UI respectively,
which is configured during installation.

webMethods API Gateway Getting Started 11.1 13


2 Deployment

meteringConfiguration.xml is the configuration file for the metering functionality. Add


this configuration file from where the docker container starts, so that the configuration file
gets looked up from PWD, which is present working directory.

apigw-svc is the host information of the Docker container that is set, and apigw is the name
of the container that is set.

cp.icr.io/cp/webmethods/api/api-gateway:11.x specifies the Docker image to use for the


container.

The docker run is parameterized with the Integration Server and the webApp port exposed
by the Docker container. If you have configured different ports for Integration Server and UI,
use the corresponding ports in the command.

You can check the status of the API Gateway Docker container, apigw by running the following
command:
docker ps

Wait until the status of the container turns healthy to start using API Gateway.

The Elasticsearch container uses the environment variable apigw_elasticsearch_hosts. The


Kibana instance uses apigw_kibana_dashboardInstance.

Once the API Gateway container is running, start the Kibana container using the following
command:
docker run --name kibana-svc --net apigw -d -p 5601:5601 \
--env ELASTICSEARCH_HOSTS=http://elastic-svc:9200 \
--env SERVER_BASEPATH=/apigatewayui/dashboardproxy \
docker.elastic.co/kibana/kibana:8.12.2

3. Start using API Gateway.

Open http://defaulthost:defaultport of Integration Server and API Gateway.

Integration Server:
http://localhost:5555

Port is the HTTP port of Integration Server configured during installation; by default, 5555.

API Gateway:
http://localhost:9072

Port is the HTTP port of API Gateway configured during installation; by default, 9072.

The home page of API Gateway appears after you log in using the default Username and
Password (Administrator and manage).

14 webMethods API Gateway Getting Started 11.1


2 Deployment

You are now ready to create and manage APIs using API Gateway.

Troubleshooting Tips

If the status of the container does not turn healthy, you can check the docker logs using the following
command:
docker logs --follow [container_id]

For example,
docker logs --follow [a7101d3e49d5]

The container_id is generated when you run the API Gateway container.

Next Steps

In case you want to stop the containers, use following commands:

Use the docker stop command to stop the API Gateway, Elasticsearch, and Kibana containers.
A sample docker stop command is as follows:
docker stop elastic-svc
docker stop apigw-svc
docker stop kibana-svc

Use the docker rm command to remove the stopped containers. A sample docker rm command
is as follows:
docker network rm apigw
docker rm elastic-svc
docker rm apigw-svc
docker rm kibana-svc

Setting JVM Heap Size

webMethods API Gateway Getting Started 11.1 15


2 Deployment

The API Gateway container image sets the initial JVM heap size to 2GB and the maximum JVM
heap size to 4GB by default.

You can adjust the default settings using the environment variables:

apigw_wrapper_java_initmemory for the initial heap size.

apigw_wrapper_java_maxmemory for the maximum heap size.

A sample command to start the API Gateway container with the modified heap sizes is as follows:
docker run -d -p 5555:5555 -p 9072:9072 \
--env apigw_elasticsearch_hosts=elastic-svc:9200 \
--env apigw_kibana_dashboardInstance=http://kibana-svc:5601 \
--env apigw_wrapper_java_initmemory=4096 \
--env apigw_wrapper_java_maxmemory=8192 \
--hostname apigw-svc \
--net apigw \
--name apigw cp.icr.io/cp/webmethods/api/api-gateway:11.x

Using Volume Mapping for Archive and Restore

Archive and restore API Gateway data from a file system outside the Docker container by adding
the following parameter to the Docker run command:
-v /home/user/archives:/tmp/default

In this command, /home/user/archives is the directory for storing the API Gateway archives.

Base Image

API Gateway references the official RedHat UBI 9 image as its base image.

Additional Resources

For details about optional arguments and additional Docker commands, see IBM webMethods
API Gateway Administration.

For details about how to set up API Gateway Docker Container with Externalized Elasticsearch
and external Kibana, see IBM webMethods API Gateway Administration.

For details about Docker and container technology, see Docker documentation, https://
docs.docker.com/.

For details about the important system settings to be considered before you start API Gateway,
see external Elasticsearch documentation, https://www.elastic.co/guide/index.html.

Docker Security related best practices

For detailed guidelines about security best practices, see Docker Security documentation,
https://docs.docker.com/engine/security/.

For details about the script that can test containers and their hosts' security configurations
against a set of best practices provided by the Center for Internet Security, see Docker bench,
https://github.com/docker/docker-bench-security.

16 webMethods API Gateway Getting Started 11.1


2 Deployment

For details about how to establish a secure configuration baseline for the Docker Engine, see
https://www.cisecurity.org/benchmark/docker for Information Security (CIS) Docker Benchmark
(Docker CE 17.06).

For details about potential security concerns associated with the use of containers and
recommendations for addressing these concerns, see SP 800 publication (Application Container
Security Guide), https://csrc.nist.gov/publications/sp800.

How Do I Install API Gateway using IBM Installer?


Let's see how to install API Gateway using IBM webMethods Installer.

Before you begin

Ensure that you have installed external Elasticsearch and external Kibana Version 8.12.2. For
detailed instructions on how to install external Elasticsearch, see https://www.elastic.co/
downloads/elasticsearch.

Download the IBM webMethods Installer to the system where you want to install API Gateway.

To install API Gateway

1. Double-click to open the IBM webMethods Installer.

2. In the Credentials tab, provide your credentials in the Username and Password fields and
click Next.

3. In the Directory tab, modify the installation folders, if required, and click Next.

4. In the Products tab, select API Gateway from the list of IBM products and click Next.

webMethods API Gateway Getting Started 11.1 17


2 Deployment

5. In the Configure tab, set the Default product administrator password. Click Next.

6. In the Configure tab, the default primary ports 5555 for the Integration Server instance and
9999 for the diagnostic port appear. Modify the ports, if required, and click Next.

18 webMethods API Gateway Getting Started 11.1


2 Deployment

7. Modify the default values of HTTP port and HTTPS port, if required. They are, by default,
9072 and 9073 respectively. Click Next.

8. Select Embedded Database in the Database Connection section and click Next.

9. Check the specified configuration and click Install.

All the selected products are installed. If there are any failures during the installation process,
refer to the installer logs for more information.

Next steps

a. Connect to external Elasticsearch and Kibana. For detailed instructions on how to connect
to external Elasticsearch and Kibana, see “Connecting to Elasticsearch Database and Kibana
” on page 20.

webMethods API Gateway Getting Started 11.1 19


2 Deployment

b. After connecting to the Elasticsearch database and Kibana, launch and log on toAPI
Gateway. For detailed instructions on how to launch API Gateway, see “Launching and
logging on to API Gateway” on page 21.

Connecting to Elasticsearch Database and Kibana


API Gateway requires Elasticsearch database to store its data and Kibana to visualize data as part
of the analytics dashboard. You must download Elasticsearch and Kibana and perform
configurations to enable your API Gateway instance to use it.

To connect API Gateway to external Elasticsearch database

1. Download the latest supported version of Elacticsearch for the current API Gateway version
from the following URL: https://www.elastic.co/downloads/elasticsearch

2. Unzip the downloaded Elasticsearch folder.

3. Configure Elasticsearch. For detailed information on how to configure Elasticsearch, see https://
www.elastic.co/guide/en/elasticsearch/reference/current/settings.html.

4. Navigate to SAG_Install_Dir/IntegrationServer/packages/WmAPIGateway/config/resources/
elasticsearch .

5. Open config.properties.

6. Set the values for the following properties:

pg.gateway.elasticsearch.autostart to false.

pg.gateway.elasticsearch.hosts to localhost:9240.

7. Save the configuration of the config.properties file.

8. Open analyticsds.properties.

9. Set the value of the property apigw.analytics.ds.hosts to localhost:9240.

10. Save the configuration of the analyticsds.properties file.

The connection is established.

To connect API Gateway to Kibana

1. Download the latest version of Kibana from the following URL: https://www.elastic.co/
downloads/kibana

2. Unzip the downloaded Kibana folder.

3. Configure Kibana. For detailed information on how to configure Kibana, see https://
www.elastic.co/guide/en/kibana/current/settings.html.

4. Navigate to Install_Dir/Kibana/Kibana-${ES_VERSION}/bin.

5. Open command prompt in this location and run the following command:

20 webMethods API Gateway Getting Started 11.1


2 Deployment

bat 'start cmd.exe /c kibana.bat --port=9405


--server.basePath="/apigatewayui/dashboardproxy" --server.host="0.0.0.0"
--elasticsearch.hosts="
http://localhost:9240"
--pid.file="kibana.pid" &'

The connection is established.

Launching and logging on to API Gateway


To launch and log on to API Gateway

1. Start Elasticsearch 8.12.2.

2. On the Windows system, go to , type Start Integration Server, and press Enter

On successful startup you should see a message.

3. Type the URL in the format http://defaulthost:defaultport in your browser's address bar
and press Enter.

For example, http://localhost:9072. Here, 9072 is the default HTTP port configured when
installing API Gateway.

4. Provide your Username and Password, and click Log in.

The default user name is Administrator and password is manage.

On successful login the home page appears. Now, you can create and manage APIs using API
Gateway.

5. After launching API Gateway, start Kibana 8.12.2.

Troubleshooting Tips: Starting and configuring Elasticsearch


and Kibana
1. What happens when I start API Gateway without Elasticsearch?

If Elasticsearch is not configured, the server.log displays the following exception indicating a
missing configuration:
Cannot invoke
"com.softwareag.apigateway.core.datastore.AbstractDataStoreClient.getDataStoreConfiguration()"
because the return value of
"com.softwareag.apigateway.core.datastore.ElasticsearchClientFactory.getDataStoreClient()"
is null.

When API Gateway initialization fails, the WmAPIGateway package does not load and the UI is
not accessible. For more information regarding the supported Elasticsearch and Kibana versions
and their compatibility with different systems, see IBM webMethods API Gateway Administration.

webMethods API Gateway Getting Started 11.1 21


2 Deployment

2. Does the installer provide any indications about the Elasticsearch dependency when I select
API Gateway?

The installer does not provide any indication of the Elasticsearch and Kibana dependency.

3. How can I verify if my API Gateway instance is connected to Elasticsearch?

You can verify the connection between API Gateway and the Elasticsearch if you are able to
perform the following steps:

Log in to API Gateway.

Able to view the Kibana dashboard.

Check API Gateway health. For more information on API Gateway health check, see IBM
webMethods API Gateway Administration.

22 webMethods API Gateway Getting Started 11.1


3 Create your first REST API
■ Creating a REST API by importing an API from a file .................................................... 24

■ Creating a REST API by importing an API from a URL .................................................. 26

■ Testing a REST API ........................................................................................................ 28

webMethods API Gateway Getting Started 11.1 23


3 Create your first REST API

API Gateway provides the ability to view, create, and manage REST APIs, and publish the APIs
to a configured destination for consumption. This section describes how you can create your first
REST API in API Gateway.

What is a REST API?

Representational State Transfer (REST) protocol defines a set of architectural principles that allow
accessing and manipulating resources by using capabilities already built into HTTP using HTTP
methods. The following are the key points of REST protocol:

Serves the data directly on HTTP

Easier and faster to access the data

In API Gateway, you can create REST APIs by importing it in two ways:

Using file

Using URL

Creating a REST API by importing an API from a file


Let's look at a sample scenario, where you are creating a REST API by importing the SearchCruise
file.

Before you begin

Ensure that you have

Downloaded the REST API file with the required specifications.

Manage APIs or Activate / Deactivate APIs functional privilege. If you are an Administrator
you would have this privilege by default.

To create a REST API by importing an API from a file

1. Click APIs in the title navigation bar.

2. Click Create API.

3. Select Import from file.

24 webMethods API Gateway Getting Started 11.1


3 Create your first REST API

4. Click Browse and select the SearchCruise.zip file.

5. Click Open

If the Swagger parser is a self-contained file with no external references, you can upload
directly. If the imported REST API file contains external references, the entire set of files must
be uploaded as a ZIP file with a structure as referenced by the imported file. In such case, API
Gateway displays the Root File Name field. Provide the root file name in the ZIP folder that
you want to import. In this example, the root file name is SearchCruise.json.

6. Provide the API name as Search Cruise in the Name field.

7. Provide the version number as 1.0 in the Version field.

8. Select the Type as Swagger as the imported Search Cruise API is a swagger file.

9. Provide a description as Import search cruise API in the Description field.

10. Select the team as Administrator for which you want to assign the Search Cruise in the Team
field.

This field appears only when the Team feature is enabled. It displays only the teams that you
are a part of.

11. Click Create.

The Search Cruise API is created and the API details screen displays.

webMethods API Gateway Getting Started 11.1 25


3 Create your first REST API

Next steps

Now that you have created the REST API, you must

Check whether the Petstore API is imported properly by using any of the API testing tools.
For details on how to test the API, see “Testing a REST API” on page 28

Creating a REST API by importing an API from a URL


Let's look at a sample scenario, where you are importing https://petstore.swagger.io/v2/swagger.json
URL to create the Petstore REST API.

Before you begin

Ensure that you have

The URL from where you want to import the API

Manage APIs or Activate / Deactivate APIs functional privilege. If you are an Administrator
you would have this privilege by default.

To create a REST API by importing an API from a file

1. Click APIs in the title navigation bar.

2. Click Create API.

3. Select Import from URL.

26 webMethods API Gateway Getting Started 11.1


3 Create your first REST API

4. Provide the URL as https://petstore.swagger.io/v2/swagger.json.

As the provided URL is public, you do not have to select the Protected check box. If you have
given the restricted access URL and if the URL is password protected, then you must select
the Protected check box. After you select the Protected check box, API Gateway displays the
Username and Password fields. Make sure you provide the login credentials of the given
restricted access URL.

Based on the specification used in the imported file, API Gateway auto populates the Type
field. REST API supports the Open API, RAML,or Swagger specifications. As the
https://petstore.swagger.io/v2/swagger.json URL is a swaggerfile, API Gateway, by default,
selects the file type as Swagger.

5. Provide the API name as Petstore in the Name field.

6. Provide the version number as 1.0 in the Version field.

7. Select the Type as Swagger as the imported Search Cruise API is a swagger file.

8. Provide a description as Import REST API using URL in the Description field.

9. Select the team as Administrator for which you want to assign the Petstore in the Team field.

This field appears only when the Team feature is enabled. It displays only the teams that you
are a part of.

10. Click Create.

The Petstore API is created and the API details screen displays.

webMethods API Gateway Getting Started 11.1 27


3 Create your first REST API

You can use this Petstore API for the following:

Find purchase order in a pet store by Order ID

Get the pet store’s inventory status

Next steps

Now that you have created the REST API, you must

Check whether the Petstore API is imported properly by using any of the API testing tools.
For details on how to test the API, see “Testing a REST API” on page 28

Testing a REST API


You can test a REST API by invoking the REST API URI in postman. Specify the REST API URI
with the required method in the format as follows:

You can customize or shorten the base path of the REST API URI by creating URL aliases. To know
more about how to create URL aliases, see IBM webMethods API Gateway Administration.

Let's test the SearchCruise REST API, which was imported using a file. In this example, to test
whether the SearchCruise API is created successfully, let's search a cruise with cruise ID 00001
using the SearchCruise API. The API response should include the details of the requested cruise.

To test a REST API using Postman

1. In the Postman UI, select the http method as GET as the search is performed using the cruise
ID.

2. Invoke the endpoint, http://host_name/gateway/SearchCruise/10.2/cruises/{CrusieID}.

28 webMethods API Gateway Getting Started 11.1


3 Create your first REST API

3. In the Authorization tab, select the type as Basic Auth and provide the login credentials of the
API Gateway instance.

4. Click Send.

The REST API is invoked successfully and returns the status code as 200. Also, the response
contains the details of the Cruise. You can now expose the API to the consumers.

webMethods API Gateway Getting Started 11.1 29


3 Create your first REST API

30 webMethods API Gateway Getting Started 11.1


4 Create your first SOAP API
■ Creating a SOAP API by importing an API from a file .................................................... 32

■ Creating a SOAP API by importing an API from a URL ................................................. 35

■ Testing a SOAP API using SOAPUI ............................................................................... 37

■ Testing a SOAP API using curl ....................................................................................... 39

webMethods API Gateway Getting Started 11.1 31


4 Create your first SOAP API

API Gateway provides the ability to view, create, and manage SOAP APIs, and publish the APIs
to a configured destination for consumption. This section describes how you can create your first
SOAP API in API Gateway.

What is a SOAP API?

Simple Object Access Protocol (SOAP) is a messaging protocol that enables users to view and
manipulate resources in a standard and secure way. A SOAP API provides a web service to perform
operations (such as create, read, update, and delete) on the resources. The data is typically
exchanged in XML format.Web Services Description Language (WSDL) is an XML-based language
for describing web services. The WSDL document describes the endpoints, operations, data types
in the SOAP message, protocol, and data format for each operation. The WSDL document contains
the following elements: types, message, portType, and binding.

A SOAP message is an XML document containing the following elements:

An envelope element - Identifies the XML document as a SOAP message.

A header element - Contains header information.

A body element - Contains call and response information.

A fault element - Contains errors and status information

Why you may still be using SOAP APIs in your organization?

A few reasons you may still be using SOAP APIs in your system:

Legacy systems might support only XML.

Requirement to support multiple modes of transport such as HTTP, HTTPS, SMTP, JMS.

Lack of support for other content types but just XML.

Supports WSS (Web Services Security) and SSL.

Built-in ACID (Atomicity, Consistency, Isolation, Durability) compliant transactions providing


data reliability, safety, and privacy.

Creating SOAP API using Import Option

In API Gateway, you can create SOAP APIs by importing it in two ways:

Using file

Using URL

Creating a SOAP API by importing an API from a file


Let's look at a sample scenario, where you are creating a SOAP API by importing the
numberconversion.wsdl file.

Before you begin

Ensure that you have

32 webMethods API Gateway Getting Started 11.1


4 Create your first SOAP API

Downloaded the SOAP API file numberconversion.wsdl with WSDL specifications from https://
www.dataaccess.com/webservicesserver/numberconversion.wso?WSDL.

Manage APIs or Activate / Deactivate APIs functional privilege. If you are an Administrator
you would have this privilege by default.

To create a SOAP API by importing an API from a file

1. Click APIs in the title navigation bar.

2. Click Create API.

3. Select Import from file.

4. Click Browse and select the numberconversion.wsdl file.

5. Click Open

Based on the specification used in the imported file, API Gateway auto populates the Type
field. SOAP API supports the WSDL specifications.

6. Provide the API name as NumberConverter in the Name field.

7. Provide the version number as 1.0 in the Version field.

8. Select the Type as WSDL as the imported NumberConverter API is a WSDL file.

9. Provide a description as Converts numbers to word or dollars in the Description field.

10. Select the team as Administrator for which you want to assign the Search Cruise in the Team
field.

webMethods API Gateway Getting Started 11.1 33


4 Create your first SOAP API

This field appears only when the Team feature is enabled. It displays only the teams that you
are a part of.

11. Click Create.

The NumberConverter API is created and the API details screen displays.

The API is created with the following operations:

NumberToDollars

NumberToWords

12. Now that you have created the NumberConverter API, you can check whether it is imported
properly by using any of the API testing tools.

34 webMethods API Gateway Getting Started 11.1


4 Create your first SOAP API

To know more about how to test the REST API using postman, see “Testing a SOAP API using
SOAPUI” on page 37.

Creating a SOAP API by importing an API from a URL


Let's look at a sample scenario, where you are creating the Calculator SOAP API by importing
from the http://www.dneonline.com/calculator.asmx?wsdl URL

Before you begin

Ensure that you have

The URL from where you want to import the API

Manage APIs or Activate / Deactivate APIs functional privilege. If you are an Administrator
you would have this privilege by default.

To create a REST API by importing an API from a file

1. Click APIs in the title navigation bar.

2. Click Create API.

3. Select Import from URL.

4. Provide the URL as http://www.dneonline.com/calculator.asmx?wsdl.

As the provided URL is public, you do not have to select the Protected check box. If you have
given the restricted access URL and if the URL is password protected, then you must select
the Protected check box. After you select the Protected check box, API Gateway displays the
Username and Password fields. Make sure you provide the login credentials of the given
restricted access URL.

Based on the specification used in the imported file, API Gateway auto populates the Type
field. SOAP API supports the WSDL specifications. As the
http://www.dneonline.com/calculator.asmx?wsdl URL is a WSDL file, API Gateway, by default,
selects the file type as WSDL.

webMethods API Gateway Getting Started 11.1 35


4 Create your first SOAP API

5. Provide the API name as Calculator in the Name field.

6. Provide the version number as 1.0 in the Version field.

7. Select the Type as WSDL as the imported Calculator API URL references a WSDL file.

8. Provide a description as Performs basic calculations on the numbers provided in the


Description field.

9. Select the team as Administrator for which you want to assign the Petstore in the Team field.

This field appears only when the Team feature is enabled. It displays only the teams that you
are a part of.

10. Click Create.

The Calculator API is created and the API details screen displays.

The Calculator API is created with the following operations:

Add

Divide

Multiply

Subtract

11. Now that you have created the Calculator API, you can check whether it is imported properly
by using any of the API testing tools.

To know more about how to test the REST API using postman, see “Testing a SOAP API using
SOAPUI” on page 37.

36 webMethods API Gateway Getting Started 11.1


4 Create your first SOAP API

Testing a SOAP API using SOAPUI


You can test the SOAP API by invoking the API from SOAPUI. SOAPUI is just one example of a
third-party SOAP test client.

Let's test the NumberConverter SOAP API, which was imported using a file. In this example, with
the imported SOAP API, you can convert a number to the word format.

To test the SOAP API using SOAPUI

1. In the SOAPUI, select SOAP in the menu bar.

2. In the New SOAP Project, add the following fields:

Project Name = Your_Project_Name

Initial WSDL field = Value in the Documentation > Artifacts fields in API Gateway

Select the Create Requests field.

webMethods API Gateway Getting Started 11.1 37


4 Create your first SOAP API

Click OK.

3. Select Projects > Your_Project_Name > NumberConversionSOAPBinding >


NumberToWords > Request1.

4. Add a number 25 in the placeholder marked by ?

5. In the Authorization tab, select the type as Basic and provide the login credentials of the API
Gateway instance.

6. Click Run.

38 webMethods API Gateway Getting Started 11.1


4 Create your first SOAP API

The SOAP API is invoked successfully and returns the status code as 200. The number is
displayed in words in the response body. You can now expose the API to the consumers.

Testing a SOAP API using curl


You can test the SOAP API by invoking the gateway endpoint in the curl. SOAP messages must
be specified completely as curl is a tool for transferring data from or to a server using any of the
following protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS,
LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, SMB, SMBS, SMTP,
SMTPS, TELNET or TFTP.

Let's test the NumberConverter SOAP API, which was imported using a file. In this example, with
the imported SOAP API, you can convert a number to the word format.

To test the SOAP API using curl

1. Start the commad prompt.

2. Add the following request body in a file as curl is a tool to transfer data from or to a server
without SOAP support. Therefore, messages must be specified completely.

3. Save the file as c:\Test\curl-test.xml.


typescript
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://www.dataaccess.com/webservicesserver/">
<soapenv:Header/>
<soapenv:Body>
<web:NumberToWords>
<web:ubiNum>25</web:ubiNum>
</web:NumberToWords>
</soapenv:Body>
</soapenv:Envelope>

You can copy the XML content in the soapenv:Body from either of the following: API Gateway
> Operations > NumberToWords > SOAP11 > Input Message OR API Gateway > Operations
> NumberToWords > SOAP12 > Input Message

4. In the command prompt, run the following command:


typescript
curl -v -H "Content-Type: text/xml; charset=utf-8" -d @ c:\Test\curl-test.xml
-X POST http://hostname:5555/ws/NumberConverter/1.0

webMethods API Gateway Getting Started 11.1 39


4 Create your first SOAP API

The SOAP API is invoked successfully and returns the status code as 200. The number converted
into words is displayed in the response body. You can now expose the API to the consumers.

40 webMethods API Gateway Getting Started 11.1


5 Create your first GraphQL API
■ Creating a GraphQL API by Importing an API from URL ............................................... 42

■ Creating a GraphQL API by Importing an API from a File .............................................. 44

■ Testing a GraphQL API using Postman .......................................................................... 45

webMethods API Gateway Getting Started 11.1 41


5 Create your first GraphQL API

API Gateway provides the ability to view, create, and manage GraphQL APIs, and publish the
APIs to a configured destination for consumption. API Gateway supports proxying an existing
GraphQL API endpoint and provides API management capabilities to clients like authentication
and analytics. This section describes how you can create your first GraphQL API in API Gateway.

In API Gateway, you can create GraphQL APIs by importing it in two ways:

Importing an API from URL

Importing an API from a file

Creating a GraphQL API by Importing an API from URL


Let’s look at a sample scenario, where you are creating a GraphQL API, Star Wars API, by importing
an API from URL.

Before you begin

Ensure that you have:

Manage APIs or Activate/Deactivate APIs functional privilege. If you are an Administrator,


you would have this privilege by default.

A GraphQL API base URL to create an API using the importer. For example, you can use the
base URL https://raw.githubusercontent.com/graphql/swapi-graphql/master/schema.graphql.

To create a GraphQL API by importing an API from URL

1. Click APIs in the title navigation bar.

2. Click Create API.

3. Select Import API from URL.

4. Provide the URL as


https://raw.githubusercontent.com/graphql/swapi-graphql/master/schema.graphql.

5. Select Protected to make the API a protected API and provide the Username and Password.

6. Provide a description for the API in the Description field.

7. Type a name for the API name in the Name field. For example, Starwars_GraphQL_URL.

8. Select GraphQL SDL from the Type dropdown menu

9. Provide the version number as 1.0 in the Version field.

10. Select the team as Administrator for which you want to assign the API in the Team field

42 webMethods API Gateway Getting Started 11.1


5 Create your first GraphQL API

This field appears only when the Team feature is enabled. It displays only the teams that you
are a part of.

11. Click Create.

A GraphQL API is created with the default Straight Through Routing policy.

12. Click Edit to replace the Endpoint URI of the Straight Through Routing policy.

For the API to work, you must replace the Endpoint URI of the default Straight Through
Routing policy with the query string of the native API.

13. Navigate to Policies > Routing > Straight Through Routing and replace the
${sys:query_string} alias in the Endpoint URI with the query string of the native API.

Here, use the native API endpoint of the Star Wars API, that is,
https://swapi-graphql.netlify.app/.netlify/functions/index.

14. Click Activate.

15. Click Yes in the confirmation dialog box.

The API is now activated. The API Gateway endpoint is now available, and consumers can
use this endpoint to invoke the API.

Next steps

Now that you have created the REST API, you must

Assess the GraphQL API is working as expected by testing it using one of the API testing tools.
For details on how to test this API, see “Testing a GraphQL API using Postman” on page 45

webMethods API Gateway Getting Started 11.1 43


5 Create your first GraphQL API

Creating a GraphQL API by Importing an API from a File


Let’s look at a sample scenario, where you are creating a Star Wars GraphQL API by importing a
file.

Before you begin

Ensure that you have:

Manage APIs or Activate/Deactivate APIs functional privilege. If you are an Administrator,


you would have this privilege by default.

A GraphQL SDL (GraphQL Schema Definition Language) file to create an API using the
importer.

To create a GraphQL API by importing an API from a file

1. Click APIs in the title navigation bar.

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. For example, choose the Starwars.graphql file.

6. Type a name for the API name in the Name field. For example, Starwars_GraphQL_file.

7. Provide a description for the API in the Description field.

8. Select GraphQL SDL from the Type dropdown menu

9. Provide the version number as 1.0 in the Version field.

10. Select the team as Administrator for which you want to assign the API in the Team field

This field appears only when the Team feature is enabled. It displays only the teams that you
are a part of.

44 webMethods API Gateway Getting Started 11.1


5 Create your first GraphQL API

11. Click Create.

A GraphQL API is created with the default Straight Through Routing policy.

12. Click Edit to replace the Endpoint URI of the Straight Through Routing policy.

For the API to work, you must replace the Endpoint URI of the default Straight Through
Routing policy with the query string of the native API.

13. Navigate to Policies > Routing > Straight Through Routing and replace the
${sys:query_string} alias in the Endpoint URI with the query string of the native API.

Here, use the native API endpoint of the Star Wars API, that is,
https://swapi-graphql.netlify.app/.netlify/functions/index.

14. Click Activate.

15. Click Yes in the confirmation dialog box.

The API is now activated. The API Gateway endpoint is now available, and consumers can
use this endpoint to invoke the API.

Next steps

Now that you have created the GraphQL, you must

Assess the GraphQL API is working as expected by testing it using one of the API testing tools.
For details on how to test this API, see “Testing a GraphQL API using Postman” on page 45

Testing a GraphQL API using Postman


You must assess the GraphQL API created is working as expected before exposing it to the API
consumers. You should verify the correct status code of the response. For instance, successful

webMethods API Gateway Getting Started 11.1 45


5 Create your first GraphQL API

HTTP requests should return 200 OK, creating a resource should return 201 CREATED, and so
on.

Let’s test the Starwars GraphQL API, which was imported using a file. In this example, to test
whether the Star Wars API is created successfully, let’s retrieve all the films in the Star Wars
franchise using the Starwars API. The API response should list all the films in the Star Wars
franchise.

Before you begin

Ensure that you have:

Postman installed in your system, or you can you use the web version of Postman.

A sample Star Wars Postman collection. For example, GraphQL.postman_collection.json.

1. Open Postman.

2. Click Import.

3. Select GraphQL and select the GraphQL.postman_collection.json file from your local folder.

4. Click Import.

5. Open the imported GraphQL API collections and select Starwars API GW.

46 webMethods API Gateway Getting Started 11.1


5 Create your first GraphQL API

6. Select a method. For example, select the method as POST.

7. Specify the request URL. For example, provide the Star Wars endpoint from the API you
created.

8. Set the request body type as GraphQL

9. Pass the query in the QUERY section. For example, write a query to fetch a list of all the films
in the Star Wars franchise.

webMethods API Gateway Getting Started 11.1 47


5 Create your first GraphQL API

10. Click Send.

The GraphQL API is invoked successfully and returns the status code as 200 OK HTTP. The
response lists all the films in the Star Wars franchise.

The API is tested and working as expected. You can now expose the API to the consumers.

48 webMethods API Gateway Getting Started 11.1


6 Publish an API to Developer Portal
You can expose APIs that you create in API Gateway to consumers by publishing them to a
Developer Portal. Developer Portal lists the published APIs and their versions, provides
documentation of their functionality and allows to register applications.

This section describes how to configure a Developer Portal instance as a destination, publish your
Search Cruise REST API to Developer Portal, view the published API from Developer Portal, and
try out the API in Developer Portal.

Before you begin

Ensure the Search Cruise API you want to expose is created.

To publish an API to Developer Portal

1. Ensure you have configured Developer Portal as a destination to publish your API.

If you have not configured the destination, perform the following steps:

Log onto API Gateway instance.

Expand the menu options icon , in the title navigation bar.

Select Administration.

Click Destinations > API Portal > Configuration

webMethods API Gateway Getting Started 11.1 49


6 Publish an API to Developer Portal

Provide the Username and Password for API Gateway configuration.

Click Publish to save the destination details.

2. Ensure the API you want to publish is activated.

This is required so that the consumers can access the gateway localhost and use the API.

If the API is not in active state, perform the following steps:

Click APIs on the title navigation bar.

Select Search Cruise API from the list of APIs and click Activate to activate the API.

3. Publish the API to Developer Portal.

Click APIs on the title navigation bar to view the API list.

Click for the Search Cruise API.

Select Developer Portal and select the required communities. The default community is
public, and all users have access to this community.

Click Publish.

50 webMethods API Gateway Getting Started 11.1


6 Publish an API to Developer Portal

The API is published to Developer Portal. A success message displays when the API is
successfully published to Developer Portal.

4. View the published API in Developer Portal.

Log onto Developer Portal instance.

Click API gallery in the title navigation bar.

You can see the published API.

5. Try out the API.

In the API gallery page, click View details > Try API for Search Cruise.

Select a stage of the API you want to test in the Environment field.

The applications associated with the selected stage appear in the Applications field.

Click the Application to be tested and select a resource from the list that appears.

Select a method and type in a value for the path and query parameters and its corresponding
value.

Select Authorization > Authorization type and provide the corresponding API key.

Type in the required Header names and corresponding values in the Headers tab.

Click Send.

The request and the response of the API appear.

webMethods API Gateway Getting Started 11.1 51


6 Publish an API to Developer Portal

52 webMethods API Gateway Getting Started 11.1


7 Monitor your API
Understanding the usage and performance of your APIs is crucial for enhancing their functionality,
diagnosing issues, and making informed business decisions. Addressing the following queries
contributes to API improvements and informed decision-making.

How are your APIs performing over time?

Which APIs are frequently utilized or under-utilized?

When is API response time optimal?

API Gateway offers comprehensive monitoring capabilities to address these challenges. It collects
and analyses data concerning the availability and performance of both the API Gateway and the
APIs themselves. This proactive approach enables the swift identification of issues that could
potentially impact users (API developers and product owners).

The analytics dashboard in the API Gateway UI displays a variety of charts to provide an overview
of API Gateway performance and its API usage. The dashboard has various filters that you can
apply depending on what you want to monitor.

API Gateway dashboard

Displays API Gateway-wide analytics. The following graphic explains the information that you
can view in various widgets in the API Gateway dashboard. You can use this information depending
on what you want to monitor:

webMethods API Gateway Getting Started 11.1 53


7 Monitor your API

API-specific dashboard

Displays API-specic analytics. The following graphic explains the information that you can view
in various widgets in the API-specific dashboard. You can use this information depending on
what you want to monitor:

54 webMethods API Gateway Getting Started 11.1


7 Monitor your API

Before you begin

Ensure that you have

Manage APIs or Activate / Deactivate APIs functional privilege. If you are an Administrator
you would have this privilege

Postman installed in your system, or you can you use the web version of Postman

How to monitor API-specific analytics?


Let's look at an example, where you secure REST APIs, Petstore_V1 and Petstore_V2, with an API
key and enforce Log Invocation policy so that you can monitor the total number of invocation and
its success and failure invocation from it's API-specific dashboards.

To view API-specific analytics

1. Create a REST API Petstore_V1.

a. Click APIs in the title navigation bar.

b. Click Create API.

c. Select Import API from URL.

d. Provide the following information:

URL: https://petstore.swagger.io/v2/swagger.json

Name: Petstore_V1

Version: 1.0

webMethods API Gateway Getting Started 11.1 55


7 Monitor your API

e. Click Create.

The Petstore_V1 API is created and the API details page appears.

f. Click Activate to activate the API.

2. Enforce the API with the Identify and Access policy to configure the identification type as API
Key.

a. Click Edit.

b. Click the Policies tab.

c. Click Identify & Access in the policy catalog section.

d. Click + next to Identify & Authorize to add the policy.

e. Provide the following information in the policy properties section:

Condition type: OR

Identification type: API Key

Application lookup condition: Registered applications

f. Click Traffic Monitoring in the policy catalog section.

g. Click + next to Log Invocation to add the policy.

h. Select the following in the policy properties section:

Store Request Headers

Store Request Payload

Store Response Headers

Store Response Payload

API Gateway

i. Click Save. The API is now enforced with the required policy.

3. Create an application api_consumer1 and api_consumer2 and associate the Petstore_V1 API to
the application. Adding the API to the application enables the application to access the API.
An API developer while invoking the API at runtime, must provide the API key for API
Gateway to identify the application.

a. Click Applications in the title navigation bar.

b. Click Create application.

c. Provide the following information:

Name: api_consumer1

Version: 1.0
56 webMethods API Gateway Getting Started 11.1
7 Monitor your API

d. Click Continue to Identifiers >

e. Click Continue to APIs >

f. Type the keyword Petstore in the search box to find the API Petstore_V1 and click + to add
the API.

g. Click Save. The application is now saved and the application details page appears.

Note:
Similary, create another application named api_consumer2 and associate to the API
Petstore_V1.

4. Make a note of the API key to use to access the API.

5. Authenticate and access the petstore API using the API key.

webMethods API Gateway Getting Started 11.1 57


7 Monitor your API

In this example, we use the Postman application to invoke and access the API.

a. Open Postman.

b. In the Postman UI, select the http method as GET to retrieve the details of the pets by
status.

c. Invoke the endpoint, http://host:port/gateway/Petstore_V1/1.0/pet/store/inventory

d. In the Header tab, provide the following information:

Key: x-Gateway-APIKey

Value: The API key of the application api_consumer1

Key: x-Gateway-APIKey

Value: The API key of the application api_consumer2

e. Select any one of the API key.

f. Click Send. The REST API is invoked successfully and returns the status code as 200. The
response contains the requested inventory data.

In case the API key is invalid, you should see an error accessing the API as follows with
the status code 401.

58 webMethods API Gateway Getting Started 11.1


7 Monitor your API

6. Monitor API-specific analytics.

a. Click APIs in the title navigation bar.

b. Click the API Petstore_V1.

c. Click Analytics to view the analytics of the API.

webMethods API Gateway Getting Started 11.1 59


7 Monitor your API

The API Invocation widget displays the total invocation count and API invocation - Status
wise widget displays the successful invocation count and failure invocation count.The
Response Code Trend widget displays the trend chart based on the response code of the
API Petstore_V1.

Note:
Similarly follow the same steps and create another API named *Petstore_V2 and monitor
its API-specific analytics.

How to monitor API Gateway-wide analytics?


Let's look at an example, where you filter the REST APIs, Petstore_V1 and Petstore_V2 and monitor
the total number of invocation and its success and failure invocation from the API Gateway-wide
dashboard.

60 webMethods API Gateway Getting Started 11.1


7 Monitor your API

To view API Gateway-wide analytics

1. Click User menu in the title navigation bar and select Analytics.

The API Gateway-wide dashboard appears displaying all the analytics of all the APIs.

2. Select the period for which you want to view the analytics.

3. Click + Add Filter and provide the following information:

Field: apiName

Operator: is one of

Values: petstore_v1, petstore_v2

4. Click Save. The API Gateway-wide dashboard appears displaying the analytics pertaining to
the APIs Petstore_V1 and Petstore_V2.

5. Click + Add Filter and provide the following information:

Field: applicationName

Operator: is one of

Values: api_consumer1, api_consumer2

6. Click Save. The API Gateway-wide dashboard appears displaying the analytics pertaining to
the filtered APIs and applications.

webMethods API Gateway Getting Started 11.1 61


7 Monitor your API

The Overall events and Application activity widgets display the graphs based on the
invocations and application consumptions.

62 webMethods API Gateway Getting Started 11.1


8 Debug an API
Why Debug an API?

Debugging an API allows faster identification and debugging of failed runtime requests.

The tracer in API Gateway has the debugging capability which, when enabled, lists the API requests
made. Tracer supports runtime request life cycle monitoring in API Gateway. Inspecting the failed
runtime requests helps you to debug and troubleshoot your API calls.

Note:
You can only trace REST, SOAP, and OData API calls.

Before you begin

Ensure that you have:

Manage APIs or Activate /Deactivate API's functional privileges.

To debug an API

1. Create a REST API by importing an API from a URL

Click APIs in the title navigation bar.

Click Create API

Click Import API from URL

Provide the following information:

URL: https://petstore.swagger.io/v2/swagger.json

Name: Petstore Debugging

Version: 1.0.6

Description: Import REST API using URL

Type: Swagger

webMethods API Gateway Getting Started 11.1 63


8 Debug an API

2. Click on the Activate button to activate API.

The API details page displays the Basic information, Technical information, Resources, methods,
and selected API specifications.

3. Click on Enable tracing.

When you enable tracer, API Gateway captures a large amount of data, which might impact
the performance and availability of the product. Hence, it is recommended to disable the tracer
when not needed.

4. Now you can invoke REST API URI in Postman. To know how to invoke API using Postman
follow the below steps:

Open Postman and create a new request.

Set the request method to GET and provide the URL:


http://host:port/gateway//Petstore%Debugging/1.0.6/pet/1

Click the Send button to invoke the endpoint .

64 webMethods API Gateway Getting Started 11.1


8 Debug an API

Once the API is successfully invoked, a success message appears, allowing you to access
the details in the Tracer tab.

5. Click the Tracer tab to view the trace details of Petstore Debugging.

6. The Trace API page displays the Runtime events, Policies applied, and Event tracer details
sections.

webMethods API Gateway Getting Started 11.1 65


8 Debug an API

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

The Runtime events section displays the list of runtime events. When you click Runtime event
by default it refreshes the Policies applied and Event tracer details sections. Event tracer
details display General Information, API request and response, and Server logs sections. In
the Policies applied section, click the stage name for which you want to view the trace details.

7. In the Runtime events section, you can find Refresh, Filter, Import and View events, and

Exportoptions.

a. Filter : To filter the runtime events, click

66 webMethods API Gateway Getting Started 11.1


8 Debug an API

and select the time interval using Quick select and Commonly used filters. The Runtime
events section displays the list of runtime events based on the applied filter.

b. Import and View events: In the Runtime events section, Click to import the
archived runtime requests. The Import and view events pop-up window displays. Browse
the runtime requests file that you want to import and View.

c. Export: In the Runtime events section, select the runtime event that you want to export

or download. Click to export the runtime request.

webMethods API Gateway Getting Started 11.1 67


8 Debug an API

68 webMethods API Gateway Getting Started 11.1


9 API Mocking
During API development, you might have the following concerns:

How can I test my API while my native API is still under development?

How can I continuously test my APIs on an ongoing basis, for example, CI-CD pipelines,
without any external dependencies, especially, under circumstances where the backend is
subjected to downtimes or requires access credentials that are changed quite frequently?

Mocking is the capability that helps you accelerate your development lifecycles by reducing the
dependencies between your development teams, especially the API consumer and the backend.
API Gateway helps mock an API. The mocked API provides realistic native API responses to
requests. You can mock an API by simulating the native API, using the API mocking capability
in API Gateway. For example, if you have an API without native implementation, you can mock
that API. When the API is invoked, the mock API server returns the mocked response to the client
that invoked the API.

API Gateway allows you to modify the default mocked response and configure it, as required, for
each combination of resource, operation, status code, and content-type based on the examples and
schemas specified in that API. In addition, you can add a condition to the operation in the resource.

API Gateway supports mocking ability for both REST and SOAP APIs. This example explains how
you can use the mocking functionality for a REST API. In this example, you enable mocking for
a REST API, PetStore API, modify the mocking details, and verify the mocked response as per the
configured mocked response.

The following figure shows the high-level steps for mocking an API.

Step 1: Enable API Mocking

webMethods API Gateway Getting Started 11.1 69


9 API Mocking

1. Log on to API Gateway.

2. Select APIs > PetStore.

3. Click API Details tab

4. Ensure that the API is in Deactivate state.

If the API is not in deactivated state, click Deactivate and click Yes to confirm.

5. Click the ellipsis icon and select Enable mocking.

Step 2: Enrich Mocking

1. Select APIs > PetStore.

2. Click Edit > API mocking.

3. Select /pet/findByStatus resource from the list of resources.

4. To add a response of your own:

a. Click Add Response and select Status code. Select 200 from the drop-down menu.

b. Click Add to add it to the existing code list.

5. In certain instances, the mock API server sends mocked response based on certain conditions
and parameters. You can add a condition to the operation by performing the following steps:

a. Click Add Conditions and specify the Condition name, for example, SuccessNoContent.

b. Select the type of Condition parameter to which the condition must be applied.

c. Specify the Key value, which can be a JSON path or XML path.

d. Add a value to your condition.

e. Select a status code, say 204, from the drop-down list.

70 webMethods API Gateway Getting Started 11.1


9 API Mocking

Note:
To use the code 506, you must enable the property Send native provider fault in the section
Administration > General > API fault. The query parameter must be set to expectStatusCode,
while invoking an API, to have correct mock responses for status codes 100 and 202.

6. If you want to add a response header for the API, perform the following steps:

a. Select Add Response Header and specify the Header key as MockedResponse and Header
value as True. These values are contained in the HTTP response.

b. Click Add to add the header value to the list of response headers.

7. Similarly, to add a content-type to the selected status code, perform the following steps:

a. Click Add content-type and select a content type value from the drop-down list.

b. Specify a mock response payload for the selected content-type value.

c. Select Add to save your selection. You can add multiple content-types.

8. Click Save to save your changes. There are multiple options to mock an API. For more
information regarding different ways to mock an API, see IBM webMethods API Gateway User's
Guide.

Step 3: Validate Mocked Response

1. Activate the Petstore API by clicking the Activate button.

2. Navigate to the Technical information tab and copy the link under Gateway localhost(s) or
copy http:/env233186.apigw-aw-eu.webmethods.io/gateway/Petstore/2

webMethods API Gateway Getting Started 11.1 71


9 API Mocking

3. Open Postman.

4. Open a new tab and paste this link under Untitled request.

5. Click Send to get the mocked response.

6. To disable mocking, click Deactivate to deactivate the API.

7. Click ellipsis and select Disable mocking.

8. Click Activate to activate the API.

9. Go to Postman and click Send. You now see the actual response of the Petstore API.

72 webMethods API Gateway Getting Started 11.1


9 API Mocking

webMethods API Gateway Getting Started 11.1 73


9 API Mocking

74 webMethods API Gateway Getting Started 11.1


10 Authenticate your API
Exposing APIs exposes application logic and sensitive data and can pose a security risk to an
organization. Without authentication, APIs are vulnerable to unauthorized access, misuse, and
abuse. Unauthenticated users or applications can potentially access sensitive data or resources,
perform unauthorized actions, or overload the API with excessive requests. This is why API
security becomes an important aspect. One of the ways you can secure your APIs is to implement
authentication mechanisms that control their exposure through user credentials and encrypted
access codes. The authentication mechanism works as a gatekeeper that grants access to only
authentic users.

How do you select the right API authentication method?

There are different API authentication methods such as HTTP basic authentication, API key
authentication, OAuth 2.0 authentication, JWT authentication.

Selecting the right authentication method for a particular API depends on the level of security
that is required to validate the clients as against the ease of implementation. For example, the
HTTP Basic authentication works well for restricting public access to low-risk data and resources,
but still requires a minimum level of security controls. API key authentication works well in
scenarios where API providers want to identify individual clients and regulate their permissions
as required. API keys are suitable for simple API requests where you might not require a high
level of security, whereas OAuth 2.0 or JWT authentication methods offer a greater level of security
in the form of token revocation and refresh tokens.

API Gateway provides various authentication methods such as Basic Auth, API key, OAuth 2.0,
OAuth with OpenID, JWT and so on. In this example, let's try to understand how to securely access
APIs using the API key-based authentication. The API key authentication method uses
system-generated strings that consist of a long series of letters or numbers to create unique pairs
of identifying credentials and API access tokens. This code of numbers calls programs from a
different application; the key then recognizes the code, its developer, the end-user, and the
application where the API call is made from. When the client authenticates the API key, the server
recognizes their identity and lets them access data with ease.

The figure depicts the API key-based authentication mechanism.!

webMethods API Gateway Getting Started 11.1 75


10 Authenticate your API

Before you begin

Ensure that you have:

Manage APIs or Activate / Deactivate APIs functional privilege. If you are an Administrator
you would have this privilege.

Postman installed in your system, or you can you use the web version of Postman.

Let's look at an example, where you secure a REST API, Petstore, with an API key and how do you
use this API key to access the API.

To authenticate and access an API using API Key

1. Create a REST API Petstore.

a. Click APIs in the title navigation bar.

b. Click Create API.

c. Select Import API from URL.

d. Provide the following information:

URL: https://petstore.swagger.io/v2/swagger.json

Name: Petstore

Version: 1.0

Team: Administrator

76 webMethods API Gateway Getting Started 11.1


10 Authenticate your API

e. Click Create. The Petstore API is created and the Petstore API details page appears.

f. Click Activate to activate the API.

2. Enforce the API with the Identify and Access policy to configure the identification type as API
Key.

a. Click Edit.

b. Click Policies tab.

c. Click Identify & Access in the policy catalog section.

d. Click + for the policy Identify & Authorize to add the policy.

e. Provide the following information in the policy properties section:

Condition type: OR

Identification type: API Key

Application lookup condition: Registered applications

webMethods API Gateway Getting Started 11.1 77


10 Authenticate your API

f. Click Save. The API is now enforced with the required policy

3. Create an application petstore app and associate the Petstore API to the application.

Adding the API to the application enables the application to access the API. An API developer
while invoking the API at runtime, must provide the API key for API Gateway to identify the
application.

a. Click Applications in the title navigation bar.

b. Click Create application.

c. Provide the following information:

Name: petstore app

Version: 1.0

d. Click Continue to Identifiers >

e. Click Continue to APIs >

f. Type the keyword pet in the search box to find the API Petstore and click + to add the API.

78 webMethods API Gateway Getting Started 11.1


10 Authenticate your API

g. Click Save. The application is now saved and the application details page appears

4. Make a note of the API key to use to access the API.

5. Authenticate and access the petstore API using the API key

In this example, we use the Postman application to invoke and access the API.

a. Open Postman.

b. In the Postman UI, select the http method as GET to retrieve the details of the pets by
status.

webMethods API Gateway Getting Started 11.1 79


10 Authenticate your API

c. Invoke the endpoint, http://host:port/gateway/Petstore/1.0/pet/findByStatus

d. In the Authorization tab, select the type as API Key and provide the following information:

Key: x-Gateway-APIKey

Value: The API key

Add to: Header

e. Click Send.

The REST API is invoked successfully and returns the status code as 200. The response
contains the requested search data.

In case the API key is invalid, you should see an error accessing the API as follows with
the status code 401.

80 webMethods API Gateway Getting Started 11.1


10 Authenticate your API

webMethods API Gateway Getting Started 11.1 81


10 Authenticate your API

82 webMethods API Gateway Getting Started 11.1


11 Rate limit your APIs
■ Configuring rate limiting for an API ................................................................................. 86

■ Testing the ratelimit API .................................................................................................. 88

webMethods API Gateway Getting Started 11.1 83


11 Rate limit your APIs

API rate limiting is a technique that is used to limit the number of invocations made to an API
during the specified time interval. Limiting the number of invocations prevents overloading the
API and in turn improves its performance.

Using the Traffic Optimization policy in API Gateway, you can limit the number of API invocations
during a specified time interval. When the number of invocations exceeds the configured limit,
API Gateway sends alerts to a specified destination.

Rate limiting algorithm in API Gateway

API Gateway uses the Token Bucket algorithm for API rate limiting to control request flow. API
Gateway maintains a bucket of tokens for each API and rate limit policy definition. The bucket
holds tokens up to a configured threshold, which determines the maximum number of requests
allowed within a given time frame. For each incoming request, a token is removed from the bucket.
If there are sufficient tokens, the request is processed. Conversely, if the bucket is empty and no
tokens are available, the request is rejected.

The API starts the time interval for token replenishment when it becomes active. For example, if
the API allows 10,000 requests per hour starting at 4:30 PM, the interval lasts until 5:30 PM. After
this interval, the API refills the bucket with the predefined number of tokens, and a new interval
begins.

Clustered Environment and Token Buckets

In a clustered environment, each node maintains its own bucket of tokens and must be
synchronized. To improve performance and efficiency in clustered environments, prefetch tokens
are used. Prefetched tokens are replenished more efficiently, reducing the need for frequent
synchronization with the central bucket. This ensures that each cluster node can handle requests
more smoothly, improving the overall performance.

For example, in a cluster configured with three nodes and a prefetch setting of 10 tokens, each
node can fetch and store 10 tokens locally. When a request arrives, it consumes a token from the
local prefetch cache. If the local cache is depleted, the node requests more tokens from the central
bucket.

Prefetch tokens offer benefits such as reduced latency, as fetching tokens from the central bucket
is minimized. However, there are limitations, including potential token wastage if a node fetches
tokens but does not receive enough requests to use them. These unused tokens cannot be shared
with other nodes until the local cache is empty.

The Traffic optimization policy generates two types of events when the specified limit is breached:

Policy violation event. Indicates the violations that occur for an API. If there are 100 violations,
then 100 policy violation events are generated.

Monitor event. Controlled by the alert frequency configuration specified in the policy.

The following illustration explains how the configured ratelimit restricts the API invocation.

84 webMethods API Gateway Getting Started 11.1


11 Rate limit your APIs

Why and when do you configure rate limiting?


API providers configure rate limit to:

Prevent resource abuse. There could be cases in which a single consumer performs an
unexpected number of invocations to an API. This overloads the system and affects API's
performance. Hence, as an API provider, you can configure a rate limit to prevent such a usage.

Manage traffic. As an API provider, you provide certain SLAs to your consumers and if you
have a large consumer base for your APIs then it is vital to control the traffic rate of your APIs.
You can use rate limiting to manage traffic to an API, ensuring that it is highly available and
responsive when handling requests from many consumers.

Controlling resource usage. Resources cost money. The number of API invocations is directly
proportional to the consumption of resources such as hosting provider, third-party agents and
so on. By setting rate limits, you can control the number of resources that are used by each
client.

Protect from malicious activities. Restricting requests over a period also helps to minimise
the risk of attackers and protects your resources from malicious activities.

Rate limiting considerations


You can configure rate limit in conjunction with other API policies such as Identify & Authorize
policy, Traffic management policy and so on.

For the proper usage of the rate limit, you can configure for protection and the quota for
monetization, you must understand the fundamental difference between both:

webMethods API Gateway Getting Started 11.1 85


11 Rate limit your APIs

Rate limit Quota

Specifies the number of requests that can be Specifies the number of requests that a consumer
made to an API over a relatively shorter period can make to an API over a longer period, such as
such as second or minute. per day, per week, or per month.

Useful for managing traffic and preventing Useful for controlling the usage over a longer
overload of an API in real-time. period and ensuring fair use of API resources.

Configuring rate limiting for an API


In this example, let us see the steps to enforce rate limit as 10 for the API, Petstore. That is, the
policy does not allow more that ten invocations to the API.

To configure rate limit

1. Click APIs in the title navigation bar.

A list of available APIs appears.

2. Click Create API.

3. Select Import from URL.

4. Provide Petstore in the Name field.

5. Provide the URL, https://petstore.swagger.io/v2/swagger.json.

6. Click Create.

The Petstore API is created and the API details screen displays.

7. Click Edit.

8. Click Policies tab.

9. Click Traffic Monitoring from the Policy Catalog section and click Traffic optimization.

The policy is added. By default, the values Total Request Count and Greater than are selected in
the Rule Name and Operator fields respectively.

86 webMethods API Gateway Getting Started 11.1


11 Rate limit your APIs

10. Provide 5 in the Value field.

When the number of invocations go beyond five, the policy is considered violated.

11. Select Consumer-specific throttling and type .*, and select Each consumer.

This is to specify that the configured invocation limit must apply to each consumer application
individually.

12. Select API Gateway under Destinations.

The policy violation alerts are displayed in the API analytics page.

13. Provide 1 in the Alert Interval field and select Minutes in the Unit field.

14. Select Every Time in the Alert Frequency field to log a event every time the API is invoked
beyond the specified limit.

15. Provide Number of invocations reached the maximum limit. Please try later in the Alert message
field.

webMethods API Gateway Getting Started 11.1 87


11 Rate limit your APIs

16. Click Save.

The policy is enforced to the Petstore API. When the number of invocations go beyond 10, the
policy violation event is displayed in the API analytics page.

Next Steps

Now that you have applied rate limit to an API, you must check whether the policy applied to the
Petstore API works as expected. For details on how to test the API, see “Testing the ratelimit
API” on page 88.

Testing the ratelimit API


To test the API ratelimit using Postman

1. Invoke the API for more than five times using a REST client. In this example, the API is invoked
for more than five times.

2. Notice the change in API response.

API response till the rate limit is reached.

88 webMethods API Gateway Getting Started 11.1


11 Rate limit your APIs

API response after the rate limit is reached.

3. Navigate to the API analytics page.

4. View the bar graph plotted for the violation events for the Last 15 minutes.

webMethods API Gateway Getting Started 11.1 89


11 Rate limit your APIs

5. View the Runtime events section to view the alert message that you provided during policy
configuration.

90 webMethods API Gateway Getting Started 11.1


12 API Transaction Logging
Why API Transaction Logging?

You can enable transaction logging for API to record and view the activities of your API. This
record keeps a track of when an event occurred, why it occurred and what was impacted. The
audit logs provide a detailed record of various auditable events of an API such as user login and
logout details and the user responsible for it. By logging the transactions of the API, you can learn
more about API activities, which may be useful for troubleshooting if something goes wrong.

API Gateway has the capability to log transactions and capture data of various auditable events
of APIs. By default, API Gateway does not log the transactions. You must enable transaction
logging so that the log data for the API to view the analytics of the API and detect anomalies.

This section describes how to activate the online_petstore API in API Gateway, enable transaction
logging of the API, and view the logs and analytics at the API level.

Before you begin

Ensure the API you are working with is created and enforced with the required policies.

1. Ensure online_petsore API is activated.

Before enabling audit API, you must first activate it so that the users can access the gateway
localhost and use the API.

If the API is not in active state, perform the following steps:

a. Log onto your API Gateway instance.

b. Click APIs on the title navigation bar.

c. Select online_petsore API from the list of APIs and click to activate the API.

2. Enable transaction logging API.

a. Click online_petstore > Policies .

webMethods API Gateway Getting Started 11.1 91


12 API Transaction Logging

b. Expand the Traffic Monitoring tab on the left pane.

c. Click Log Invocation.

d. Select the required Log Invocation policy properties in the right pane and select API
Gateway as the Destination.

92 webMethods API Gateway Getting Started 11.1


12 API Transaction Logging

e. Click Save.

Note:
If you want to apply the transaction logging changes to all the APIs, you can use a global
policy.

3. View the analytics data.

a. Go to Postman.

b. Set the request method to GET and type the URL


http://host/port/gateway/online_petsore/1.0.6

c. Click the Send button to invoke the endpoint.

d. On the API Gateway instance, click APIs on the title navigation bar.

e. Select online_petstore API > Analytics.

This displays the API-specific transaction data.

webMethods API Gateway Getting Started 11.1 93


12 API Transaction Logging

Transaction logging data with payload properties:

Transaction logging data without payload properties:

This chart specifies the number of events generated at a specific time. The analytics data
remains the same regardless of whether the payload log invocation properties are selected
or not.

The headers and the payload log data are saved when the payload properties are enabled.
In this case, the size of the data increases drastically. If the payload properties are disabled,
then only the headers are saved. The size of the data is minimal.

You can sort the data by selecting the required options in the filter.

94 webMethods API Gateway Getting Started 11.1


13 Request and Response Transformation
■ Use case 1: E-Commerce API Request Header Transformation .................................... 96

■ Use case 2: Response Message Transformation ........................................................... 99

■ Testing Request and Response Transformation Policies .............................................. 101

webMethods API Gateway Getting Started 11.1 95


13 Request and Response Transformation

API Gateway plays a crucial role in managing and facilitating communication between different
services in a microservices architecture or between clients and servers. Request and response
transformation in API Gateway involves modifying the format or content of incoming requests
or outgoing responses to meet the requirements of both the clients and the services.

Let's explore this concept with a use case. Imagine you are managing an e-commerce website, and
you want to implement request and response transformations to improve security and customize
the response.

Use case 1: E-Commerce API Request Header Transformation


You want to enhance the security of your e-commerce API by implementing a custom security
header, X-Api-Consumer-Secret, in the incoming requests. This header must carry an API secret
key and be present in all requests. You can use this header to authorize API requests.

Before you begin

Ensure that you have:

Manage APIs or Activate/Deactivate APIs functional privilege. If you are an Administrator,


you would have this privilege by default.

A sample REST API file to create an API using the importer. For example, ConsumerAPI.

To transform the API request header

1. Click APIs in the title navigation bar.

2. Click Create API to create an e-commerce REST API. For example, ConsumerAPI.

3. Select Import API from file. Click Browse and select the ConsumerAPI file.

4. Provide the following details:

a. Name: ConsumerAPI

b. Description: E-commerce API

96 webMethods API Gateway Getting Started 11.1


13 Request and Response Transformation

c. Version: 1.0

5. Click Create.

6. Click Edit to add the Request Transformation policy.

7. Select Policies > Request Processing > Request Transformation.

The Request Transformation policy properties section appears.

8. In the Condition section, select OR.

The configured transformation is applied when at least one of the conditions is satisfied.

Note:
The condition can also be set to AND operator. The configured transformation is applied
only when all the set conditions are satisfied.

9. Click Add Condition to configure the conditions to evaluate the contents on the request.

webMethods API Gateway Getting Started 11.1 97


13 Request and Response Transformation

10. Provide the following information:

a. Variable: ${request.headers.X-Api-Consumer-Secret}

b. Operator: Equals

c. Value: xyz

This condition checks for the presence of the X-Api-Consumer-Secret header with a specific
value. In this case, xyz.

11. Click Add.

The condition to authorize the API request is created.

12. Select Transformation Configuration > Header/Query/Path transformation.

98 webMethods API Gateway Getting Started 11.1


13 Request and Response Transformation

The Header/Query/Path transformation section appears.

13. In Add/Modify section, provide the following information:

a. Variable: X-Api-Provider-Secret

b. Value: 123

14. Click Add.

15. Click Save.

If the condition to authorize the API request is met, API Gateway transforms the request by
adding a new header, X-Api-Provider-Secret with the API secret key value 123 and authorizes
the API request.

Use case 2: Response Message Transformation


You want to display a custom message based on the response, depending on the value of the
X-Api-Provider-Secret header.

Before you begin

Ensure that you have Manage APIs or Activate/Deactivate APIs functional privilege. If you are
an Administrator, you would have this privilege by default.

To transform the response message

1. Click APIs in the title navigation bar.

A list of available APIs appears.

2. Open e-commerce API. For example, ConsumerAPI.

webMethods API Gateway Getting Started 11.1 99


13 Request and Response Transformation

3. Click Edit to add the Response Transformation policy to the Consumer API.

4. Select Policies > Response Processing > Response Transformation.

The Response Transformation policy properties section appears.

5. In the Condition section, select OR.

The configured transformation is applied when at least one of the conditions is satisfied.

Note:
The condition can also be set to AND operator. The configured transformation is applied
only when all the set conditions are satisfied.

6. Click Add Condition to configure the conditions to evaluate the contents on the request.

7. Provide the following information:

a. Variable: ${request.headers.X-Api-Provider-Secret}

b. Operator: Equals

c. Value: Accepted

8. Click Add.

The condition checks the value of the X-Api-Provider-Secret header to determine the
appropriate transformation. In this case, Accepted.

9. Select Transformation Configuration > Status Transformation.

100 webMethods API Gateway Getting Started 11.1


13 Request and Response Transformation

The Status Transformation policy properties section appears.

10. Provide the following information:

a. Code: ${response.statusCode}

b. Message: Request has been processed successfully.

11. Click Save.

API Gateway checks the value of the X-Api-Provider-Secret header to determine the
appropriate transformation. If the header value is Accepted, the response status message is
modified to indicate that the request is processed successfully.

Next steps

Now that you have created a e-commerce REST API and implemented the request and response
transformation policies, ensure the applied policies work as expected by utilizing API testing
tools. For details about how to test the API, see “Testing Request and Response Transformation
Policies” on page 101.

Testing Request and Response Transformation Policies


You can test request and response transformation policy by invoking the REST API URI in Postman.
Specify the REST API URI with the required method in the format as follows:

webMethods API Gateway Getting Started 11.1 101


13 Request and Response Transformation

Let's test the request and response transformation policies applied for the ConsumerAPI example.
In this example, to test whether the request and response transformation policies are working as
expected, let's the invoke the API endpoint by adding the X-Api-Consumer-Secret header with the
API secret key value xyz. The API request should be authorized and retrieve the product information
with the customized response.

Before you begin

Ensure that you have Postman installed in your system, or you can you use the web version of
Postman.

To test request and response transformation policies using Postman

1. In the Postman UI, select the HTTP method as GET.

2. Invoke the endpoint, http://hostname/gateway/ConsumerAPI/1.0/product.

3. In the Authorization tab, select the type as Basic Auth and provide the login credentials of the
API Gateway instance.

4. In the Headers tab, provide the following details:

a. Key: X-Api-Consumer-Secret

b. Value: xyz

5. Click Send.

102 webMethods API Gateway Getting Started 11.1


13 Request and Response Transformation

The REST API is successfully invoked, transforming the request and response according to
the applied policies for request and response transformation, displaying the customized
response along with the product details.

webMethods API Gateway Getting Started 11.1 103


13 Request and Response Transformation

104 webMethods API Gateway Getting Started 11.1


14 Global Policies
Global policies are a set of policies associated globally with all APIs or a selected set of APIs.

When you create an API, you can enforce a policy only at the API level. If an organisation wants
to enforce a policy for multiple APIs, API Gateway provides the capability of creating a global
policy that can be applied across all APIs or a selected set of APIs depending on the requirement.
By associating policies globally to all APIs or a selected set of APIs, as an administrator you can
ensure that a set of policies is consistently applied to all APIs or a set of APIs by default. For
example, you can apply a threat protection policy to all APIs by creating a global policy that
addresses data protection and security concerns.

API Gateway provides a default system policy Transaction logging, which has log invocation
policy and filters associated to log request or response payloads to a specified destination. These
transactions are monitored and logged across all APIs in API Gateway. When you activate
Transaction logging, Logging Invocation policy is enforced on all APIs.

Let’s look at a sample scenario, where you create a global policy Transport Global. This global
policy has the Enable HTTP/HTTPS policy configured and applied to all APIs that do not have
ODATA in their name.

Ensure that you have the Manage global policies functional privilege to create a global policy.

To create a global policy and apply it to a set of APIs

1. Click Policies in the top navigation bar.

2. Click Global policies > Create global policy.

3. In the Basic information section, provide the following details:

Name - Transport Global

Description - Global Policy

webMethods API Gateway Getting Started 11.1 105


14 Global Policies

4. Click Continue to filters > or click Filters in the left navigation panel.

5. Select all the API Type.

6. Select all the HTTP methods in the Filter using HTTP methods section for this example.

7. In the Filter using attributes select the following values to filter APIs having ODATA as part
of their name.

Attribute: API Name

Operator: Not Contains

Value: ODATA

106 webMethods API Gateway Getting Started 11.1


14 Global Policies

8. Click Continue to policy configuration.

9. Select Transport and click on Enable HTTP/HTTPS to configure the policy.

10. Select the protocol HTTP in the policy properties section.

11. Click Save.

The global policy is created and the policy details page appears. It also lists the APIs for which
this global policy is configured.

webMethods API Gateway Getting Started 11.1 107


14 Global Policies

12. Click Activate to activate the global policy.

13. Verify the configured global policy.

a. Select the API Petstore Debugging from the APIs section in the global policy.

In the policies tab for the API, the globe icon for Transport > Enable HTTP/HTTPS
indicates that the policy is applied at a global level.

108 webMethods API Gateway Getting Started 11.1


15 Routing Policies
Routing policies in API Gateway determine the direction of incoming requests to different backend
resources or endpoints based on specified conditions. These policies allow you to control the flow
of traffic within API Gateway, enabling you to implement various routing strategies, such as load
balancing, versioning, A/B testing, and canary deployments.

Straight Through Routing policy is applied by default when an API is created in API Gateway.
This default behavior is suitable for APIs that route incoming requests to a single backend resource
or native endpoint.

Let’s look at a sample scenario, where you are importing https://petstore.swagger.io/v2/swagger.json


URL to create the Petstore REST API, and Straight Through Routing policy is applied by default.

Before you begin

Ensure that you have

The URL from where you want to import the API

Manage APIs or Activate / Deactivate APIs functional privilege. If you are an Administrator,
you would have this privilege

To configure Straight Through Routing policy

1. Click APIs in the title navigation bar.

2. Click Create API.

3. Select Import API from URL.

4. Provide the following information:

URL: https://petstore.swagger.io/v2/swagger.json

Name: Petstore

Description: The Petstore API is a RESTful web service that allows users to interact with
a virtual pet store.

Version: 1.0

webMethods API Gateway Getting Started 11.1 109


15 Routing Policies

5. Click Create. The Petstore API is created, and the Straight Through Routing policy is applied
by default. The Petstore API’s details page appears.

6. Click Activate to activate the API.

7. To check the Straight Through Routing policy that is applied by default, click Policies >
Routing.

In this example, the default application of Straight Through Routing policy simplifies the
API configuration process.

Once the Petstore API is configured and exposed, clients can interact with the API endpoints
to perform various actions, such as retrieving a list of available pets, adding new pets to the
store, updating pet details, placing orders, and more. API Gateway directly routes each API
request made by the client to the backend service.

The following table lists the routing policies offered by API Gateway and outlines the specific
use cases for each policy:

Use case Routing policy

Objective: Expose existing backend services Utilize Straight Through Routing policy to
through an API with minimal added ensure minimal latency and overhead.
complexity.

Scenario: Optimize traffic flow between


network segments or zones without
intermediate processing.

Example:

In fast networks like data centers,


straight-through routing minimizes latency

110 webMethods API Gateway Getting Started 11.1


15 Routing Policies

Use case Routing policy

and overhead. This approach ideally suits


applications that require low latency and high
throughput, such as real-time video streaming,
online gaming, or financial trading.

Objective: Direct incoming requests to Utilize Conditional Routing policy to handle


different backend resources based on specified data differently depending on predefined
conditions or criteria. conditions.
Scenario: Handling sensor data from various
devices differently based on specific
conditions.

Example:

In a smart agriculture system, sensors monitor


soil moisture levels across different fields.
Conditional routing directs data from sensors
detecting low moisture levels to irrigation
systems for immediate action.

Objective: Effectively distribute incoming Utilize Load Balancer Routing policy to


network traffic evenly across multiple servers evenly distribute incoming requests across
or resources to optimize resource utilization servers.
and improve system performance.

Scenario: Handling high volumes of incoming


requests in a web hosting environment.

Example:

During peak shopping seasons, an e-commerce


platform utilizes load balancer routing to
evenly distribute traffic across servers,
preventing overload and enhancing
performance for a seamless user experience.

Objective: Ensure secure communication Utilize Outbound Auth – Transport policy to


between API Gateway and backend systems authenticate outgoing requests.
by including authentication credentials within
transport headers.

Scenario: Integration with legacy systems or


third-party APIs requiring transport-level
authentication.

Example:

webMethods API Gateway Getting Started 11.1 111


15 Routing Policies

Use case Routing policy

An enterprise application interacts with a


legacy backend protected by Basic
Authentication over HTTPS.

Configuring the Outbound Auth - Transport


policy with the appropriate credentials enables
API Gateway to seamlessly authenticate and
authorize outgoing requests to the legacy
system.

Objective: Embed authentication credentials Utilize Outbound Auth – Message policy to


within the payload message of outgoing embed authentication credentials within the
requests to satisfy requirements of the native message payload for secure communication
API. with APIs.
Scenario: In instances where APIs mandate
authentication credentials within the message
payload.

Example:

An application needs to interact with a


third-party service secured with SAML-based
authentication.

By configuring the Outbound Auth - Message


policy with the necessary SAML credentials,
API Gateway seamlessly embeds these
credentials within the outgoing request’s
payload, ensuring secure communication
without added complexity.

Objective: Facilitate seamless communication Utilize JMS/AMQP Routing policy to


between a legacy system utilizing a JMS queue seamlessly route requests between the two
and a modern RESTful API. environments.
Scenario: Modernizing service by offering a
RESTful API for order placement while
maintaining compatibility with legacy
JMS-based communication.

Example:

A legacy system communicates through a JMS


queue for order processing. The company aims
to modernize its service by providing a
RESTful API for order placement.

JMS/AMQP routing policy acts as a bridge


between the legacy system and the RESTful

112 webMethods API Gateway Getting Started 11.1


15 Routing Policies

Use case Routing policy

API, ensuring smooth transition and


compatibility.

webMethods API Gateway Getting Started 11.1 113


15 Routing Policies

114 webMethods API Gateway Getting Started 11.1


16 Validate API Specification
Validating API specifications is essential to ensure that the API behaves as expected, maintains
data integrity, effectively handles errors, enforces policies, and provides security. API Validation
acts as a gatekeeper to maintain the quality and security of the API services. API Gateway provides
capability to validate API specifications that provides answers to the following concerns you might
have:

1. How can I ensure that the API consistently meets the defined schema and regulations?

2. What measures must you take to prevent the API from processing incorrect or malformed
data?

3. How do I manage errors that occur during API interactions?

API Gateway provides the request processing and response processing policies that can be used
to validate the incoming request or an outgoing response against API's various specifications such
as schema, query parameters, path parameters, cookie parameters, content-types, and HTTP
Headers referenced in their corresponding formats.

In this example, let’s see how to use the capabilities of API Gateway to validate API specifications
for an incoming request by enforcing the Request processing policy by configuring the four policy
properties, namely, Schema, HTTP Headers, Path parameters and Query Parameters to the
REST API online_petstore.

Before you begin:

Ensure that the online_petstore API is activated.

To enable Validate API specification policy

1. Log on to API Gateway.

2. Click APIs on the navigation bar.

3. Select online_petstore API.

4. Click Edit.

5. Click Policies.

6. Select Request Processing > Validate API Specification.

webMethods API Gateway Getting Started 11.1 115


16 Validate API Specification

7. Click Save.

The validate API specification policy is enforced.

8. Enable the following policy parameters to validate the API against the set specifications.

To validate the API against Schema

1. Click Policies > Edit.

2. Select Schema under policy parameters.

3. Click Save.

4. Click API Details > Resources and methods.

5. Expand /getTimeAfterJson/{time} and make a note of the inline schema.

6. Open Postman.

7. Provide the value {"latitude":1, "longitude":27} under the Body section.

8. Select the HTTP method as POST.

9. Invoke the endpoint


http://host:port/gateway/online_petstore/0.1.9/getTimeAfterJson/100

10. Click Send.

116 webMethods API Gateway Getting Started 11.1


16 Validate API Specification

The online_petstore API is invoked and returns a response since the value provided aligns
within the bounds of the inline schema.

If you provide an empty value or a value which does not adhere to the inline schema,
the validation fails, and an error with the status code 400 is displayed.

To validate the API against HTTP Headers

webMethods API Gateway Getting Started 11.1 117


16 Validate API Specification

HTTP headers are essential communication channel between clients and API Gateway,
enabling the customization of requests and responses. Validating HTTP headers ensures
security, data integrity and effective routing.

1. Click Policies > Edit.

2. Select HTTP Headers under policy parameters.

3. Click Save.

4. Click API Details > Resources and methods.

5. Expand /test-header-boolean.

Note that the data type of the selected REST resource is boolean, that is, the value must
be either true or false.

6. Open Postman.

7. Select Headers.

8. Set the value of test-header-boolean as true.

9. Select the HTTP method as POST.

10. Invoke the endpoint


http://host:port/gateway/online_petstore/1.0/test-header-boolean

The online_petstore API is invoked and returns a 200 OK status code.

118 webMethods API Gateway Getting Started 11.1


16 Validate API Specification

If you provide a data type other than boolean, the validation fails, and an error with
the status code 400 is displayed.

To validate the API against Path Parameters

In API Gateway, a path parameter is a dynamic value extracted from the segmented paths
in the HTTP request. You can configure the API request path using the format -
/path/{parameter}. This allows API Gateway to match the path in an HTTP request based
on your configured parameter path. Validating the path parameters prevents unauthorized
access and ensures accurate routing of the requests.

1. Click Policies > Edit.

2. Select Path Parameters under policy parameters.

3. Click Save.

4. Click API Details > Resources and methods.

5. Expand /integerPathParam/{intParam}.

Note that the Type of the selected REST resource is Path and Data type is Integer.

6. Open Postman.

webMethods API Gateway Getting Started 11.1 119


16 Validate API Specification

7. Select the HTTP method as POST.

8. Invoke the endpoint


http://host:port/gateway/online_petstore/1.0/IntegerPathParam/123

The endpoint is appended with the value 123, and the online_petstore API is invoked,
returning a 200 OK status code.

If you provide a data type other than integer, say string


http://host:port/gateway/online_petstore/1.0/IntegerPathParam/abc, the validation
fails, and an error with the status code 400 is displayed.

To validate the API against Query Parameters

Query Parameters are key-value pairs that appear after the ? (question mark) in the endpoint
URL. Validating these query parameters is necessary for security and reliability. It ensures
that the incoming requests conform to the expected formats, reducing the risk of
vulnerabilities and security threats.

1. Click Policies > Edit.

2. Select Query Parameters under policy parameters.

3. Click Save.

4. Click API Details > Resources and methods.

5. Expand /stringQueryParam.

Note that the Name of the selected REST resource is queryString, Type is Query and
Data type is String.

6. Open Postman.

7. Select the HTTP method as POST.


120 webMethods API Gateway Getting Started 11.1
16 Validate API Specification

8. Invoke the endpoint


http://host:port/gateway/online_petstore/1.0/stringQueryParam?queryString=abc

The name querystring is appended to the endpoint with a tring value, and the
online_petstore API is invoked, returning a 200 OK status code.

Note:
When validating a query parameter in an endpoint you want to invoke, always prefix
it with a ?.

If you provide a Name other than queryString in the endpoint, for example,
http://host:port/gateway/online_petstore/1.0/stringQueryParam?name=abc, the
validation fails and you see an error with the status code 400.

webMethods API Gateway Getting Started 11.1 121


16 Validate API Specification

122 webMethods API Gateway Getting Started 11.1

You might also like