Testing an API with the Local Test Environment

Use the Local Test Environment to test APIs on your local machine, without the need to connect to an API Connect management server. The Local Test Environment is a lightweight API Manager running on your local machine. It allows you to rapidly test APIs locally.

Note: A later version of the Local Test Environment is available. For details, see the IBM® API Connect Version 10 Local Test Environment documentation.
API Connect provides the following methods for testing an API on your local machine:
  • Invoke the API from the API Designer UI application running in Online mode as described in Testing an API with the assembly test tool.
  • Call the API in the Local Test Environment with a cURL command, as described in the following sections.
Important: The current version of the Local Test Environment is a beta release.

Prerequisites

  • The API Connect developer toolkit, including the API Designer user interface, installed. For installation and running instructions, see Installing the toolkit.
  • The Local Test Environment and the API Designer must be downloaded from the same API Connect release page on IBM Fix Central, in order for them to work together. For example, for API Connect Version 2018.4.1.7, use the distributions of Local Test Environment and API Designer from https://www.ibm.com/support/pages/ibm-api-connect-v2018417-ifix15-available.
  • Docker installed.
    Note: The Local Test Environment is not supported with Docker Version 18.09.x.
  • A minimum of 4 GB of RAM available to Docker if a single gateway type is used, or 6 GB if both the DataPower® API Gateway and DataPower Gateway (v5 compatible) are used.
    Note: As you increase the number of APIs that are published to your gateways, you will need to allocate further memory to Docker. You will also need to start the Local Test Environment with a larger database; see apic-lte start.
  • If you are using Windows, ensure that your C: drive (or the drive on which your HOME directory is located, if different), is enabled as a shared drive so that the Local Test Environment files are accessible to the Docker containers.

Installing the Local Test Environment

There are two options for installing the Local Test Environment:
  • Each user downloads the Local Test Environment images to their local machine and installs the Local Test Environment from there.
  • One user downloads the Local Test Environment images and uploads them to a private Docker registry, from where any user can install the Local Test Environment.
To install the Local Test Environment from your local machine, complete the following steps:
  1. Download the apic-lte-version.zip file from IBM Fix Central, and extract the contents, which are as follows:
    • apic-lte-images.tar.gz, which contains all required Docker images.
    • Separate apic-lte binary files for the Mac OS X, Linux®, and Windows platforms, in respective subfolders.
  2. Load the Docker images into your local Docker image repository by entering the following command:
    docker load < apic-lte-images.tar.gz
To upload the Local Test Environment images to a private Docker registry, complete the following steps:
  1. Download the apic-lte-version.zip file as described in step 1.
  2. Distribute the appropriate apic-lte binary file to all users.
  3. Upload the Local Test Environment to your private Docker registry; enter the following command:
    apic-lte registry-upload apic-lte-images.tar.gz registry_host
    where registry_host is the host name or IP address of your private Docker registry. Now, any user can install and run the Local Test Environment as follows:
    1. If the private Docker registry requires authentication, log in by entering the following command:
      docker login registry_host
    2. Load the Docker images into your local Docker image repository by entering the following command:
      apic-lte init registry_host

Starting the Local Test Environment

  1. Start the Docker images by entering the following command:
    apic-lte start
    Note:
    • By default, the apic-lte start command starts only a DataPower API Gateway. To also start a DataPower Gateway (v5 compatible), enter the following command:
      apic-lte start --datapower-gateway-enabled --datapower-api-gateway-enabled
    • The Local Test Environment might fail to start with an error message that includes the strings Error: certificate is not yet valid and CERT_NOT_YET_VALID. The most likely cause is that the date and time setting is incorrect on the machine that is the running the Local Test Environment. Ensure that the date and time setting is correct, before attempting the start command again. If you are using Docker for Windows, the clock in the Docker containers can become out of sync with the system clock, especially after a machine has been put in sleep mode. In this case, restarting Docker should fix the clock discrepancy; for more information, see https://github.com/docker/for-win/issues/4526.
  2. Verify that the Local Test Environment is installed and running correctly by entering the following commands:
    1. apic-lte status
      This output from this command shows the status of all components, and provides endpoint and authentication details, and should be similar to the following:
      Container                       Status
      ---------                       ------
      apic-lte-apim                   Up 3 minutes
      apic-lte-datapower-gateway      Not Running
      apic-lte-datapower-api-gateway  Up 2 minutes
      apic-lte-db                     Up 3 minutes
      apic-lte-juhu                   Up 3 minutes
      apic-lte-lur                    Up 3 minutes
      
      - Platform API url: https://localhost:2000
      - Admin user: username=admin, password=7iron-hide
      - 'localtest' org owner: username=shavon, password=7iron-hide
      - 'localtest' org sandbox test app credentials client id: 80963e74076afe50d346d76401c3c08a
      - Datapower API Gateway API base url: https://localhost:9444/localtest/sandbox/
    2. apic login --server localhost:2000 --username shavon --password 7iron-hide --realm provider/default-idp-2
      
      This command confirms that you can log in to the management server, and the response should be as follows:
      Logged into localhost:2000 successfully

Preparing an API for testing in the Local Test Environment

To prepare an API for testing in the Local Test Environment, you must publish it to the Sandbox Catalog in the Local Test Environment. If you want to test an API that you already published, proceed to Testing an API in the Local Test Environment., otherwise, complete the following steps:
  1. Launch the API Designer user interface.
  2. Open the required local directory; this is the directory in which your API and Product definition files will be stored.
  3. Connect to the Local Test Environment. If you haven't previously connected to the Local Test Environment, click Add Another Cloud, then complete the following steps:
    1. In the HOST URL field, enter https://localhost:2000, then click Next..
    2. In the Username field, enter shavon, in the Password field enter 7iron-hide, then click Sign in.

    If you have previously connected to the Local Test Environment, click the existing tile to log in immediately.

    The API Designer welcome page opens.

  4. Click Develop APIs and Products, then click the API that you want to test. For details on how to configure an API definition, see Developing your APIs and applications.
  5. Click the Publish this API to the Sandbox catalog icon:
    Screen capture highlighting the Publish icon (arrow)
    When the publish operation completes, your API is ready for testing.
    Note: Whenever you make any changes to an API, you must republish it before retesting.

Testing an API in the Local Test Environment.

To test an API in the Local Test Environment, issue a REST API call to the following URL:
https://localhost:9444/localtest/sandbox/basepath/operation_path?client_id=lte_client_id
where:
  • basepath is the base path that is configured in the API definition.
  • operation_path is the path for the operation that you want to invoke, as configured in the API definition.
  • lte_client_id is the client ID for the test application in the local test environment, as returned by the apic-lte status command in step 2.
The following example show how to test the API that is created in the tutorial Creating a proxy REST API definition, by using the curl utility; the API returns the details of bank branches:
curl -k https://localhost:9444/localtest/sandbox/branches/details?client_id=80963e74076afe50d346d76401c3c08a
[{"id":"0b3a8cf0-7e78-11e5-8059-a1020f32cce5","type":"atm","address":{"street1":"600 Anton Blvd.","street2":"Floor 5","city":"Costa Mesa","state":"CA","zip_code":"92626"}},
{"id":"9d72ece0-7e7b-11e5-9038-55f9f9c08c06","type":"atm","address":{"street1":"4660 La Jolla Village Drive","street2":"Suite 300","city":"San Diego","state":"CA","zip_code":"92122"}},
{"id":"ae648760-7e77-11e5-8059-a1020f32cce5","type":"atm","address":{"street1":"New Orchard Road","city":"Armonk","state":"NY","zip_code":"10504"}},
{"id":"c23397f0-7e76-11e5-8059-a1020f32cce5","type":"branch","phone":"512-286-5000","address":{"street1":"11400 Burnet Rd.","city":"Austin","state":"TX","zip_code":"78758-3415"}},
{"id":"ca841550-7e77-11e5-8059-a1020f32cce5","type":"atm","address":{"street1":"334 Route 9W","city":"Palisades","state":"NY","zip_code":"10964"}},
{"id":"dc132eb0-7e7b-11e5-9038-55f9f9c08c06","type":"branch","phone":"978-899-3444","address":{"street1":"550 King St.","city":"Littleton","state":"MA","zip_code":"01460-1250"}},
{"id":"e1161670-7e76-11e5-8059-a1020f32cce5","type":"branch","phone":"561-893-7700","address":{"street1":"5901 Broken Sound Pkwy. NW","city":"Boca Raton","state":"FL","zip_code":"33487-2773"}},
{"id":"f9ca9ab0-7e7b-11e5-9038-55f9f9c08c06","type":"atm","address":{"street1":"1 Rogers Street","city":"Cambridge","state":"MA","zip_code":"02142"}}]

Local Test Environment commands

The following table summarizes the Local Test Environment commands; use the help command to get full usage details for any command.
Table 1. Local Test Environment command summary
Command Description
apic-lte help command Display help information for any command.
apic-lte init Download the Local Test Environment Docker images.
apic-lte start Start the Local Test Environment Docker images. Use the --database-max-heap-size parameter to set the size of the Local Test Environment database, in bytes; for example:
apic-lte start --database-max-heap-size 4096M
apic-lte start --database-max-heap-size 1G
apic-lte start --database-max-heap-size 1048576K
apic-lte start --database-max-heap-size 1073741824
The default value is 1024M.
Tip: By default, the apic-lte start command deletes all previous data and re-initializes the Local Test Environment configuration, so all your previous configuration, including published Products, is deleted. To retain the previous configuration, and to apply the same command parameters that were used in the previous apic-lte start command, supply the --keep-config parameter.
apic-lte status Display status information for the Local Test Environment components, and endpoint and authentication details.
apic-lte stop Stop the Local Test Environment Docker images.
apic-lte version Display Local Test Environment version information.

Troubleshooting the Local Test Environment

You can consult the log file for each Local Test Environment microservice or database by using the following command:

docker logs container-name
where container-name is one of the following:
  • apic-lte-juhu: the authentication gateway
  • apic-lte-apim: the API Management service
  • apic-lte-lur: the Local User Registry
  • apic-lte-db: the Cassandra database of the API Management service
  • apic-lte-datapower-api-gateway: the DataPower API Gateway
  • apic-lte-datapower-gateway: the DataPower Gateway (v5 compatible)

You can access the gateway logs in either of the following ways:

  • Use the gateway administration web UI:
    1. Open the page https://localhost:web_ui_port in a browser; for details of the required port value, see Local Test Environment port values.
    2. Select the apiconnect domain and the WebGUI interface, and log in with user name admin and password admin.
    3. Click View Logs.
  • Use the gateway administration CLI:
    1. Open an SSH connection by using the following command:
      ssh -p gateway-ssh-port localhost
      For details of the required port value, see Local Test Environment port values. The user name is admin and the password is admin.
    2. Enter the command switch domain apiconnect.
    3. To view the gateway log, enter the command show log.
    4. To view the log for the communication between the gateway and the API management system, enter the command show logging gwd-log.

Local Test Environment port values

If any of the default port values for the Local Test Environment components conflict with ports already in use on your system, you can change them when you start the Local Test Environment by passing one or more --component port_value parameters to the apic-lte start command, where:
  • component is the Local Test Environment component whose port value you want to change.
  • port_value is the required value.
For example:
apic-lte start --datapower-api-gateway-api-port 9445
The following table lists the components, together with the corresponding component parameters, and the default port values:
Component component parameter Default port value
DataPower API Gateway API port datapower-api-gateway-api-port 9444
DataPower API Gateway API Connect service port datapower-api-gateway-apic-service-port 3001
DataPower API Gateway SSH port datapower-api-gateway-ssh-port 9023
DataPower API Gateway administration web UI datapower-api-gateway-web-gui-port 9091
DataPower Gateway (v5 compatible) API port datapower-gateway-api-port 9443
DataPower Gateway (v5 compatible) service port datapower-gateway-apic-service-port 3000
DataPower Gateway (v5 compatible) SSH port datapower-gateway-ssh-port 9022
DataPower Gateway (v5 compatible) administration web UI datapower-gateway-web-gui-port 9090