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.

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.
  • Call the API in the Local Test Environment with a cURL command, as described in the following sections.

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 from the same API Connect fix pack release in order for them to work together.
  • 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. Open a browser and visit the API Connect announcement page, search for your product version, and locate the "Downloads" table on the product announcement page. In the table, click the link to download each of the following files:
    • apic-lte-images-version.tar.gz, which contains all required Docker images.

      Example: apic-lte-images-10.0.2.tar.gz

    • apic-lte-platform-version, which are binary files for the Mac OS X, Linux®, and Windows platforms.
      Examples:
      • Mac OS X: apic-lte-osx-10.0.2
      • Linux: apic-lte-linux-10.0.2
      • Windows: apic-lte-win-10.0.2
  2. On the Mac OS X or Linux platform, use the chmod command to make the binary file executable; for example:
    chmod +x linux-apic-lte
  3. Load the Docker images into your local Docker image repository by entering the following command:
    docker load < apic-lte-images.tar.gz
Note: In all Local Test Environment commands that are used on the remainder of this page, replace platform with osx, linux, or windows, depending on your platform, as follows:
  • Mac OS X: replace platform-apic-lte with osx-apic-lte
  • Linux: replace platform-apic-lte with linux-apic-lte
  • Windows: replace platform-apic-lte with win-apic-lte
To upload the Local Test Environment images to a private Docker registry, complete the following steps:
  1. Download the IBM_API_CONNECT_LOCAL_TEST_ENVIRO.zip file as described in step 1.
  2. Distribute the appropriate binary file to all users, according to the platform.
  3. Upload the Local Test Environment to your private Docker registry; enter the following command:
    platform-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:
      platform-apic-lte init registry_host

Starting the Local Test Environment

  1. Start the Docker images by entering the following command:
    platform-apic-lte start
    Note:
    • By default, the platform-apic-lte start command starts only a DataPower API Gateway. To also start a DataPower Gateway (v5 compatible), enter the following command:
      platform-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.
    • By default, the LTE starts with an empty backend database that does not contain the APIs and Products that might have been published during an earlier run of the LTE. To start the LTE with the backend database that was used during the previous run, use the flag --keep-config, for example, platform-apic-lte start --keep-config. When you use --keep-config any other flag that is specified for the start is ignored. Instead the same flags that were used during the earlier start are used, in particular the same gateways are enabled.
  2. Verify that the Local Test Environment is installed and running correctly by entering the following commands:
    1. platform-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
Note: If you have previously installed toolkit credentials, as detailed in Installing the toolkit, attempting to log in to the Local Test Environment management server from the toolkit CLI will fail; you must first clear the credentials by using the following command:
apic client-creds:clear
The toolkit CLI will now use the default credentials for login to the toolkit Local Test Environment. If you subsequently log in to a management server in an API Connect cloud, the default toolkit credentials will also be used, rather than the credentials that are unique to that deployment. To use the unique credentials, re-install them by using the following command:
apic client-creds:set toolkit_credentials_file_path/credentials.json
where credentials_file_path is the location of the previously downloaded toolkit credentials JSON file.
To determine whether you currently have any toolkit credentials installed, use the following command:
apic client-creds:list

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. Move the activation slider control to the on position:
    Screen capture highlighting the activation slider control
    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 platform-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
platform-apic-lte help command Display help information for any command.
platform-apic-lte init Download the Local Test Environment Docker images.
platform-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:
linux-apic-lte start --database-max-heap-size 4096M
linux-apic-lte start --database-max-heap-size 1G
linux-apic-lte start --database-max-heap-size 1048576K
linux-apic-lte start --database-max-heap-size 1073741824
The default value is 1024M.
Tip: By default, the platform-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 platform-apic-lte start command, supply the --keep-config parameter.
platform-apic-lte status Display status information for the Local Test Environment components, and endpoint and authentication details.
platform-apic-lte stop Stop the Local Test Environment Docker images.
platform-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 Postgres 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 platform-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:
platform-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 REST management port datapower-api-gateway-rest-management-port 5555
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 API Gateway XML management port datapower-api-gateway-xml-management-port 5551
DataPower Gateway (v5 compatible) API port datapower-gateway-api-port 9443
DataPower Gateway (v5 compatible) API Connect service port datapower-gateway-apic-service-port 3000
DataPower Gateway (v5 compatible) REST management port datapower-gateway-rest-management-port 5554
DataPower Gateway (v5 compatible) SSH port datapower-gateway-ssh-port 9022
DataPower Gateway (v5 compatible) administration web UI datapower-gateway-web-gui-port 9090
DataPower Gateway (v5 compatible) XML management port datapower-gateway-xml-management-port 5550
Platform API port platform-api-port 2000