Installing the toolkit

You can install the toolkit either from npm or from a Management server in your IBM® API Connect 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 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).

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.
Ensure that node is in your PATH.
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 command-line tool, apic.
API Connect API Designer visual tool.
API Connect Micro Gateway.

You can also uninstall the toolkit and display the version number of the currently installed toolkit.

Use the version of the toolkit that corresponds to the version of your API Connect Management Server. To find the appropriate toolkit version, use the npm dist-tag ls apiconnect command. For example:

$ npm dist-tag ls apiconnect
1.0.3.0: 1.0.3
apic-v5.0.1.0: 2.0.18
apic-v5.0.2.1: 2.1.19
apic-v5.0.3.0-iFix1: 2.2.12
apic-v5.0.3.0-iFix2: 2.2.14
apic-v5.0.3.0-iFix4: 2.2.17
apic-v5.0.3.0: 2.2.9
apic-v5.0.4.0-iFix2: 2.3.10
apic-v5.0.4.0: 2.3.6
apic-v5.0.5.0: 2.4.11
apic-v5.0.6.0: 2.5.8
apic-v5.0.6.1: 2.5.17
apic-v5.0.6.2: 2.5.21
apic-v5.0.6.3: 2.5.33
apic-v5.0.6.4: 2.5.40
apic-v5.0.6.5: 2.5.52
apic-v5.0.6.6: 2.5.80
apic-v5.0.7.0: 2.6.2
apic-v5.0.7.1: 2.6.55
apic-v5.0.7.2: 2.6.71
apic-v5.0.8.0: 2.7.30
apic-v5.0.8.1: 2.7.62
apic-v5.0.8.2: 2.7.111
apic-v5.0.8.3: 2.7.209
apic-v5.0.8.4-iFix: 2.8.39
apic-v5.0.8.4: 2.8.14
apic-v5.0.8.5: 3.0.17
apic-v5.0.8.6: 4.0.x
latest: 4.0.x
v5.0.0.1: 1.0.3

Then, to install a specific version of toolkit use the command

npm install
apiconnect@<version>

. For example, if you have API Connect v5.0.6.5, use the command:

npm install apiconnect@3.0.17

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 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.

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).
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

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
```
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

Uninstall the toolkit, as described in Uninstalling the toolkit.
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.

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).
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-).