Testing APIs with the IBM DataPower Gateway

Using the API Connect Toolkit with IBM® DataPower® Gateway unlocks the full set of security and policy capabilities for local testing.

Some key benefits of this feature include: Develop and test APIs that use the full complement of IBM API Connect Assembly policies; saved changes are instantly synchronized with the Gateway for rapid testing and feedback; test product and plan level concepts such as rate-limiting; the reserved Catalog name apic-dev is available to provide substitute assembly properties at runtime; DataPower error logging is integrated into the API Designer logging console; Request/Response logging is also available from the logging console with latency data.

Before you begin

You must have the following installed and functioning properly to use this feature:

Docker v1.13 or higher.
Docker Compose v1.11 or higher.
On the Windows platform, Windows 10 Professional and Docker for Windows are required.
On the Mac platform, Docker for Mac is required.
On the Linux® platform, install Docker by following the Docker installation instructions for your particular distribution.

Note:

This feature is not available with IBM API Connect Version 5.0.8.7.
If you are using a version of Linux that includes Security-Enhanced Linux (SELinux) and you find that, after completing the steps described in this topic, you are unable to call your API, enter the command setenforce 0 to run SELinux in permissive mode, then retry. To verify that SE Linux is running in permissive mode, enter the command sestatus and check the Current mode property.
When you use Docker for Windows with Windows 10, you must adjust the Docker software settings to share the C: drive. If you choose to install Docker on Windows 7, you must use the Docker Toolbox, which includes Oracle VirtualBox. Under this configuration, Docker containers run in a VM hosted by VirtualBox. Ensure that you increase the VirtualBox resource settings to provide at least 4 GB RAM and 2 CPUs to the Docker VM (usually named default).

About this task

The Toolkit determines which gateway type to run based on the metadata that is stored in the current project's API definition YAML file based on OpenAPI (Swagger 2.0). You can manually edit this file and insert gateway: datapower-gateway as a child of the x-ibm-configuration: block. Alternatively you can select the gateway type with the API Designer Assembly view, selecting between the Micro Gateway or DataPower provider and press save. The following entry in your file indicates a selection of the IBM DataPower Gateway for API testing:


  x-ibm-configuration:
    # ... other configuration options
    gateway: datapower-gateway

When the current project's API definition file includes gateway: datapower-gateway, the API is deployed locally on a IBM DataPower Gateway, which runs within a Docker container on your workstation. When you start the DataPower Gateway, your workstation must download the Docker image from Docker Hub and perform a build step. It can take some minutes to complete this step and another minute or two to start the gateway.

You can update the OpenAPI (Swagger 2.0) YAML file manually, or with the API Designer interface as shown in the instructions that follow.

Important: From IBM API Connect Version 5.0.8.7, some commands are no longer supported by the API Connect toolkit. Such commands are indicated on this page by the V5.0.7 and earlier

icon.

Procedure

Start the API Designer.
1. Enter apic edit to start the API Designer in a new browser window.
Select your test gateway.
1. If not already open, use the Show / hide policy palette icon to view the policy palette.
2. If necessary, click the select provider icon to show the test gateways.
3. Choose DataPower Gateway policies.
  When you select a gateway, the features that are available to it become visible in the policy palette.
4. Click the save icon to save your preference in the YAML file.
Generate a gateway instance with just one of the methods that are described in this step. Allow several minutes for the gateway to come online, especially the first time it is run.
1. In the CLI, enter apic start.
2. In the test console at the bottom of the screen, click the Start the servers icon:
A completed service start displays Running next to the gateway type, URL, and the port where it is available.
Your project configuration and other running processes can produce a different gateway type, URL, or port number than is displayed in the image.
Show the test tool pane in the API Designer interface, by clicking the Test icon that is highlighted in the image .
- You are ready to continue API testing on an instance of the IBM DataPower Gateway Docker container. For further instructions, see Testing an API with the API Designer test tool.
- The new gateway entry can be viewed in the OpenAPI (Swagger 2.0) YAML file directly, or from within the Source tab in the API Designer interface.
- You can treat your testing environment as a Catalog capable of property substitutions by configuring the special apic-dev Catalog. See the section that is entitled Configuring API definitions for container run times, at ../com.ibm.apic.install.doc/tapim_migrating_to_containers.html.