Installing the toolkit

You can install the toolkit either from npm or from a Management server in your IBM® API Connect for IBM Cloud cloud.

Before you begin

Features of the toolkit include the default ability for local testing of APIs with a DataPower® Gateway Docker container. When Docker and Docker Compose are present and functioning normally on your system, the DataPower image is downloaded from Docker Hub. For more information, see: Testing APIs with the IBM DataPower Gateway.

The following steps create a software environment that is ready to install the IBM API Connect for IBM Cloud toolkit.

Note: On Windows, use the Windows command shell run as an administrator to enter Node or npm commands, instead of Powershell or Cygwin (the Windows bash shell emulator).
  1. Install Community Node.js distribution version 10, or a higher 10.x.x version. For details of supported Node.js versions, see Detailed System Requirements, then click the Prerequisites tab.
  2. Ensure that node is in your PATH.
  3. Use the npm -v command to check the version of npm and ensure that it shows 10.x.x, or higher.

About this task

You install the toolkit by using the npm command that is installed as part of Node.js. Installing the toolkit installs:
  • API Connect for IBM Cloud command-line tool, apic.
  • API Connect for IBM Cloud API Designer visual tool.
  • API Connect for IBM Cloud Micro Gateway.
You can also uninstall the toolkit and display the version number of the currently installed toolkit.

Procedure

Note: Do not use the npm configuration setting engine-strict (or use the --engine-strict option) since it will prevent installation from completing.

During installation, you may see errors from the node-gyp module, but because these errors are from an optional dependency, the installation should finish successfully.

You may also see npm warnings of Possible EventEmitter memory leak detected, but these are spurious and do not indicate a memory leak or any other issue.

To install the toolkit, complete the following steps:

  • If you are not using trusted certificates, enter the following command:
    npm config -g set strict-ssl false
  • If you are using a proxy server, enter the following commands:
    npm config set proxy http://proxy_address:port
    npm config set https-proxy http://proxy_address:port
    where proxy_address is the host name or IP address of the proxy server, and port is the port number.
  • You are going to install the toolkit globally (-g), because it includes a command line interface. You can use npm config get prefix -g to learn the location of the global installation directory. Ensure that you are installing with sufficient permissions to write system files. Install the toolkit in either of the following ways:
    • To install the toolkit from npm, enter the following command:

      npm install -g apiconnect
    • To install the toolkit from a Management server in your IBM API Connect for IBM Cloud cloud, enter the following command:

      npm install -g --unsafe-perm https://appliance/packages/apiconnect
      Where appliance is the host name or IP address of the Management server appliance.
    • To install the toolkit locally from the toolkit tarball, download the tarball .tgz file from IBM Fix Central, then enter the following command:
      npm  i -g apiconnect-version.tgz
      or if you installing from root, enter the following command:
      npm  i -g apiconnect-version.tgz --unsafe-perm
  • To display the version number of the currently installed toolkit, enter the following command:
    apic -v

What to do next

Obtain an IBM Cloud API Key for authenticating with the toolkit.

  1. Obtain the API Key by completing the following steps:
    1. Browse to the IBM Cloud Identity and Access Management page.
    2. In the navigation list, click IBM Cloud API Keys.
    3. On the IBM Cloud API Keys page, click Create an IBM Cloud API key.
    4. In the Create API key dialog box, provide a Name and a Description for your new key, and then click Create.
    5. In the Create API key message box, either Copy or Download the key to make sure you save a copy. If you save the file, it is named apiKey.json.
      Attention: Do not navigate away from the page until you have saved the key. Once you lose this message, you cannot obtain a copy of the key (in that case, delete the key and create a new one).
  2. Log in to the toolkit with the new API Key and the following command:
    apic login --server=Cloud.apiconnect.ibmcloud.com --apikey=Your_new_api_key

    In the command, Cloud is the hosted instance of API Connect you are connecting to; for example, us for US South, or eu-de for Frankfurt. In Reserved Instance, this is the host name that you use to access API Manager (begins with mgr-).

Uninstalling the toolkit

Before you begin

Before uninstalling the toolkit, stop any apps that are running locally by entering the command:
apic stop --all
Note: Configuration settings for the toolkit are stored in the home_dir\.apiconnect directory, where home_dir is the home directory of the user account under which the toolkit was installed. When uninstalling, you have the option to either keep or delete the configuration settings. The default behavior is to delete the home_dir\.apiconnect directory. Use the --no-config-clear command to preserve the configuration settings.

Procedure

  1. Uninstall using npm:
    npm uninstall -g apiconnect
    By default, this command removes the toolkit configuration settings, as described above. To keep toolkit configuration settings, instead enter the command:
    npm uninstall -g apiconnect --no-config-clear
    To uninstall the toolkit, clear your npm cache, and remove the toolkit configuration, instead enter the command:
    npm uninstall -g apiconnect
    To uninstall the toolkit, clear your npm cache, and keep the toolkit configuration, instead enter the command:
    npm uninstall -g apiconnect --no-config-clear

    To verify that the cache is consistent after uninstalling the toolkit, enter the following command:

    npm cache verify
  2. On Windows, delete all files whose names begin with npm- in C:\Users\username\AppData\Local\Temp

Updating your toolkit installation

Before you begin

Before updating your toolkit installation, be sure to stop any apps that are running locally by entering the command:
apic stop --all

Procedure

  1. Uninstall the toolkit, as described in Uninstalling the toolkit.
  2. Reinstall the toolkit by entering this command:
    npm install -g apiconnect

What to do next

If you previously used a username and password to authenticate in the API Connect Developer Toolkit, then you must start using API Key authentication instead.

  1. Obtain the API Key by completing the following steps:
    1. Browse to the IBM Cloud Identity and Access Management page.
    2. In the navigation list, click IBM Cloud API Keys.
    3. On the IBM Cloud API Keys page, click Create an IBM Cloud API key.
    4. In the Create API key dialog box, provide a Name and a Description for your new key, and then click Create.
    5. In the Create API key message box, either Copy or Download the key to make sure you save a copy. If you save the file, it is named apiKey.json.
      Attention: Do not navigate away from the page until you have saved the key. Once you lose this message, you cannot obtain a copy of the key (in that case, delete the key and create a new one).
  2. Log in to the toolkit with the new API Key and the following command:
    apic login --server=Cloud.apiconnect.ibmcloud.com --apikey=Your_new_api_key

    In the command, Cloud is the hosted instance of API Connect you are connecting to; for example, us for US South, or eu-de for Frankfurt. In Reserved Instance, this is the host name that you use to access API Manager (begins with mgr-).