API Gateway Getting Started
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
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
8 Debug an API.........................................................................................................................................63
9 API Mocking..........................................................................................................................................69
14 Global Policies...................................................................................................................................105
15 Routing Policies.................................................................................................................................109
Document Conventions
Convention Description
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.
{} 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 (...).
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 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.
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.
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.
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
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.
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.
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.
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:
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.
3. In the Entitlement key section, click Copy key to copy the entitlement key to the clipboard.
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.
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
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.
apigw-svc is the host information of the Docker container that is set, and apigw is the name
of the container that is set.
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.
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
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).
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
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
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:
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
1. Download the latest supported version of Elacticsearch for the current API Gateway version
from the following URL: https://www.elastic.co/downloads/elasticsearch
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.
pg.gateway.elasticsearch.autostart to false.
pg.gateway.elasticsearch.hosts to localhost:9240.
8. Open analyticsds.properties.
1. Download the latest version of Kibana from the following URL: https://www.elastic.co/
downloads/kibana
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:
2. On the Windows system, go to , type Start Integration Server, and press Enter
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.
On successful login the home page appears. Now, you can create and manage APIs using API
Gateway.
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.
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.
You can verify the connection between API Gateway and the Elasticsearch if you are able to
perform the following steps:
Check API Gateway health. For more information on API Gateway health check, see IBM
webMethods API Gateway Administration.
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.
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:
In API Gateway, you can create REST APIs by importing it in two ways:
Using file
Using URL
Manage APIs or Activate / Deactivate APIs functional privilege. If you are an Administrator
you would have this privilege by default.
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.
8. Select the Type as Swagger as the imported Search Cruise API is a swagger file.
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.
The Search Cruise API is created and the API details screen displays.
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
Manage APIs or Activate / Deactivate APIs functional privilege. If you are an Administrator
you would have this privilege by default.
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.
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.
The Petstore API is created and the API details screen displays.
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
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.
1. In the Postman UI, select the http method as GET as the search is performed using the cruise
ID.
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.
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.
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 few reasons you may still be using SOAP APIs in your system:
Requirement to support multiple modes of transport such as HTTP, HTTPS, SMTP, JMS.
In API Gateway, you can create SOAP APIs by importing it in two ways:
Using file
Using URL
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.
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.
8. Select the Type as WSDL as the imported NumberConverter API is a WSDL file.
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.
The NumberConverter API is created and the API details screen displays.
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.
To know more about how to test the REST API using postman, see “Testing a SOAP API using
SOAPUI” on page 37.
Manage APIs or Activate / Deactivate APIs functional privilege. If you are an Administrator
you would have this privilege by default.
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.
7. Select the Type as WSDL as the imported Calculator API URL references a WSDL file.
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.
The Calculator API is created and the API details screen displays.
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.
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.
Initial WSDL field = Value in the Documentation > Artifacts fields in API Gateway
Click OK.
5. In the Authorization tab, select the type as Basic and provide the login credentials of the API
Gateway instance.
6. Click Run.
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.
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.
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.
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
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.
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:
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.
5. Select Protected to make the API a protected API and provide the Username and Password.
7. Type a name for the API name in the Name field. For example, Starwars_GraphQL_URL.
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.
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.
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
A GraphQL SDL (GraphQL Schema Definition Language) file to create an API using the
importer.
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.
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.
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.
The API is now activated. The API Gateway endpoint is now available, and consumers can
use this endpoint to invoke the API.
Next steps
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
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.
Postman installed in your system, or you can you use the web version of Postman.
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.
7. Specify the request URL. For example, provide the Star Wars endpoint from the API you
created.
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.
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.
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.
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:
Select Administration.
This is required so that the consumers can access the gateway localhost and use the API.
Select Search Cruise API from the list of APIs and click Activate to activate the API.
Click APIs on the title navigation bar to view the API list.
Select Developer Portal and select the required communities. The default community is
public, and all users have access to this community.
Click Publish.
The API is published to Developer Portal. A success message displays when the API is
successfully published to Developer Portal.
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.
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.
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:
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:
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
URL: https://petstore.swagger.io/v2/swagger.json
Name: Petstore_V1
Version: 1.0
e. Click Create.
The Petstore_V1 API is created and the API details page appears.
2. Enforce the API with the Identify and Access policy to configure the identification type as API
Key.
a. Click Edit.
Condition type: OR
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.
Name: api_consumer1
Version: 1.0
56 webMethods API Gateway Getting Started 11.1
7 Monitor your API
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.
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.
Key: x-Gateway-APIKey
Key: x-Gateway-APIKey
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.
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.
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.
Field: apiName
Operator: is one of
4. Click Save. The API Gateway-wide dashboard appears displaying the analytics pertaining to
the APIs Petstore_V1 and Petstore_V2.
Field: applicationName
Operator: is one of
6. Click Save. The API Gateway-wide dashboard appears displaying the analytics pertaining to
the filtered APIs and applications.
The Overall events and Application activity widgets display the graphs based on the
invocations and application consumptions.
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.
To debug an API
URL: https://petstore.swagger.io/v2/swagger.json
Version: 1.0.6
Type: Swagger
The API details page displays the Basic information, Technical information, Resources, methods,
and selected API specifications.
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:
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.
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.
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
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.
If the API is not in deactivated state, click Deactivate and click Yes to confirm.
a. Click Add Response and select Status code. Select 200 from the drop-down menu.
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.
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.
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.
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
3. Open Postman.
4. Open a new tab and paste this link under Untitled request.
9. Go to Postman and click Send. You now see the actual response of the Petstore API.
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.
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.
URL: https://petstore.swagger.io/v2/swagger.json
Name: Petstore
Version: 1.0
Team: Administrator
e. Click Create. The Petstore API is created and the Petstore API details page appears.
2. Enforce the API with the Identify and Access policy to configure the identification type as API
Key.
a. Click Edit.
d. Click + for the policy Identify & Authorize to add the policy.
Condition type: OR
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.
Version: 1.0
f. Type the keyword pet in the search box to find the API Petstore and click + to add the API.
g. Click Save. The application is now saved and the application details page appears
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.
d. In the Authorization tab, select the type as API Key and provide the following information:
Key: x-Gateway-APIKey
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.
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.
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.
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.
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.
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:
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.
6. Click Create.
The Petstore API is created and the API details screen displays.
7. Click Edit.
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.
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.
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.
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.
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.
4. View the bar graph plotted for the violation events for the Last 15 minutes.
5. View the Runtime events section to view the alert message that you provided during policy
configuration.
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.
Ensure the API you are working with is created and enforced with the required policies.
Before enabling audit API, you must first activate it so that the users can access the gateway
localhost and use the API.
c. Select online_petsore API from the list of APIs and click to activate the API.
d. Select the required Log Invocation policy properties in the right pane and select API
Gateway as the Destination.
e. Click Save.
Note:
If you want to apply the transaction logging changes to all the APIs, you can use a global
policy.
a. Go to Postman.
d. On the API Gateway instance, click APIs on the title navigation bar.
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.
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.
A sample REST API file to create an API using the importer. For example, ConsumerAPI.
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.
a. Name: ConsumerAPI
c. Version: 1.0
5. Click Create.
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.
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.
a. Variable: X-Api-Provider-Secret
b. Value: 123
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.
Ensure that you have Manage APIs or Activate/Deactivate APIs functional privilege. If you are
an Administrator, you would have this privilege by default.
3. Click Edit to add the Response Transformation policy to the Consumer API.
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.
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.
a. Code: ${response.statusCode}
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.
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.
Ensure that you have Postman installed in your system, or you can you use the web version of
Postman.
3. In the Authorization tab, select the type as Basic Auth and provide the login credentials of the
API Gateway instance.
a. Key: X-Api-Consumer-Secret
b. Value: xyz
5. Click Send.
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.
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.
4. Click Continue to filters > or click Filters in the left navigation panel.
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.
Value: ODATA
The global policy is created and the policy details page appears. It also lists the APIs for which
this global policy is configured.
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.
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.
Manage APIs or Activate / Deactivate APIs functional privilege. If you are an Administrator,
you would have this privilege
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
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.
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:
Objective: Expose existing backend services Utilize Straight Through Routing policy to
through an API with minimal added ensure minimal latency and overhead.
complexity.
Example:
Example:
Example:
Example:
Example:
Example:
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?
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.
4. Click Edit.
5. Click Policies.
7. Click Save.
8. Enable the following policy parameters to validate the API against the set specifications.
3. Click Save.
6. Open Postman.
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.
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.
3. Click Save.
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.
If you provide a data type other than boolean, the validation fails, and an error with
the status code 400 is displayed.
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.
3. Click Save.
5. Expand /integerPathParam/{intParam}.
Note that the Type of the selected REST resource is Path and Data type is Integer.
6. Open Postman.
The endpoint is appended with the value 123, and the online_petstore API is invoked,
returning a 200 OK status code.
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.
3. Click Save.
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.
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.