Installing the toolkit

You can install the toolkit that provides CLI commands, and the API Designer user interface, for IBM® API Connect.

About this task

The toolkit is provided as executable files, so no actual installation is necessary, you just to need to download the required compressed file and extract the contents.

There are two toolkit options available:
  • CLI: provides a command line environment for working with IBM API Connect.
  • CLI + LoopBack + Designer: provides a command line environment for working with IBM API Connect, including LoopBack® support, and the API Designer user interface.

To install the toolkit, download the compressed file that is appropriate for your chosen toolkit option and platform, then extract the contents to a chosen location on your local machine. The compressed file contains an executable file for running CLI commands and, if you choose the CLI + LoopBack + Designer option, an executable file for launching the API Designer user interface.

You can download the toolkit compressed file in either of the following ways:
  • From IBM Fix Central.
  • From the Cloud Manager or API Manager user interface.
The following table identifies the name of the compressed file that you need to download, depending on your chosen toolkit option and platform:
Table 1. Toolkit file names, by option and platform
Toolkit option Mac OS X Linux® Windows
CLI toolkit-mac.zip toolkit-linux.tgz toolkit-windows.zip
CLI + LoopBack + Designer toolkit-loopback-designer-mac.zip toolkit-loopback-designer-linux.tgz toolkit-loopback-designer-windows.zip

Procedure

To install and run the toolkit, complete the following steps:

  1. Download the toolkit compressed file.
    • To download the toolkit from IBM Fix Central, complete the following steps:
      1. Open the IBM Fix Central site in your browser.
      2. In the Product selector field, enter API Connect, then select IBM API Connect from the drop down list.
      3. Select your installed 10.x.y version from the Installed Version list, then click Continue. If you do not know your installed IBM API Connect version, contact your administrator.
      4. In the Text field, enter toolkit, then click Continue.
      5. Select the required file, as identified in Table 1.
        Note: When you download from IBM Fix Central, the release number is appended to the file name.
      6. Click Continue, then follow the instructions to complete the download operation.
    • To download the toolkit from Cloud Manager or API Manager user interface, complete the following steps:
      1. Open the Cloud Manager or API Manager user interface.
      2. On the welcome page, click the Download Toolkit tile. The two toolkit options are listed.
      3. Click your platform alongside either the CLI option or the CLI + LoopBack + Designer option as required, then save the associated compressed file to your local file system.
      4. To download the API Designer credentials (Client ID and Client Secret), click Download alongside API Designer Credentials, then save the designer_credentials.json file to your local file system. A command is provided for installing the credentials, as described in detail in step 6.
      5. To download the toolkit credentials (Client ID and Client Secret), click Download alongside Credential, then save the credentials.json file to your local file system. A command is provided for installing the credentials, as described in detail in step 5.
      6. Close the Install API Connect Toolkit window.
  2. Extract the contents of the toolkit compressed file to a folder of your choice.
    The contents of the file depend on the your chosen toolkit option and platform, as follows:
    Table 2. Toolkit compressed file contents, by option and platform
    Toolkit option Mac OS X Linux Windows
    CLI apic-slim apic-slim apic-slim.exe
    CLI + LoopBack + Designer apic

    api_designer-mac.zip: contains the API Designer user interface application.

    apic

    api_designer-linux

    apic.exe

    api_designer-win.exe

    The apic-slim or apic-slim.exe file is the CLI for IBM API Connect.

    The apic or apic.exe file is the CLI for IBM API Connect including LoopBack support.

    Tip: If you are using the CLI option, then if you rename the apic-slim file to apic, or the apic-slim.exe file to apic.exe, you can run the CLI commands exactly as documented, copy and paste sample commands from the documentation, and use any command scripts as-is if you later move to the CLI + LoopBack + Designer option.

    The api_designer-platform file is the API Designer user interface application for the specified platform.

  3. Optional: Delete the $HOME/.apiconnect/node_clis directory.

    You need to do this only if you replaced a version of apic or apic.exe and are using the apic lb4 command. You need to delete the directory get apic to unpack the new loopback.

    On Windows, $HOME is defined by environment USERPROFILE.

  4. Run the CLI.
    • For the Mac OS X or Linux platforms, complete the following steps:
      1. Open a terminal instance and navigate to the folder where you extracted the contents of the toolkit compressed file.
      2. Make the CLI file an executable file by entering the following command:
        chmod +x download_name
        Where download_name is the name of the toolkit file that you downloaded, either apic or apic-slim.
      3. Run CLI commands as follows:
        ./apic command_name_and_parameters
        or
        ./apic-slim command_name_and_parameters
        For details of the CLI commands, see apic.
    • For the Windows platform, complete the following steps:
      1. Open a terminal window and navigate to the folder where you extracted the contents of the toolkit compressed file.
      2. Run CLI commands as follows:
        apic command_name_and_parameters
        or
        apic-slim command_name_and_parameters
        For details of the CLI commands, see apic.
    Tip: Add the folder location of your CLI file to your PATH variable so that you can run CLI commands from anywhere in your file system.
  5. Install the toolkit credentials.
    If you do not install the toolkit credentials that are provided for download, as detailed previously in the toolkit credentials download instructions, API Connect uses a pre-supplied set of credentials that are identical for all deployments. However, the downloaded credentials were generated during the deployment of your API Connect system and are unique to your installation. To install the credentials into your local toolkit, run the following command:
    apic client-creds:set toolkit_credentials_file_path/credentials.json
    where credentials_file_path is the location to which you downloaded the toolkit credentials JSON file. After you have run this command, your toolkit uses these new credentials to authenticate with the management server.
    Note: At any one time, you can use only one set of toolkit credentials for login to a management server from the toolkit CLI. If you want to log in to a different management server you must install the toolkit credentials from that management server.
    To revert to the default pre-supplied toolkit credentials for all login operations from the toolkit CLI, use the following command:
    apic client-creds:clear
    For increased security, an administrator can remove the pre-supplied credentials from the management server by completing the following steps:
    1. Log in to the management server as an administrator; see Logging in to a management server.
    2. Delete the pre-supplied credentials by running the following commands:
      apic registrations:delete toolkit --server mgmt_endpoint_url
      apic registrations:delete consumer-toolkit --server mgmt_endpoint_url
  6. Install the API Designer credentials.

    If you do not install the API Designer credentials that are provided for download, as detailed previously in the API Designer credentials download instructions, API Connect uses a pre-supplied set of credentials that are identical for all deployments. However, the downloaded credentials were generated during the deployment of your API Connect system and are unique to your installation. To install the credentials into your local API Designer, set the APIC_DESIGNER_CREDENTIALS environment variable to the credentials download location, using the mechanism appropriate for your operating system.

    If you are using Windows, set APIC_DESIGNER_CREDENTIALS=designer_credentials_file_path/designer_credentials.json by using the Environment Variables window.

    If you are using Mac OS X, you can pass in the environment variable while launching API Designer from the command line. For example:
    APIC_DESIGNER_CREDENTIALS=designer_credentials_file_path/designer_credentials.json open designer_application_file_path/'API Designer.app'
    where:
    • designer_credentials_file_path is the location to which you downloaded the API Designer credentials JSON file.
    • designer_application_file_path is the location to which you downloaded and uncompressed the API Designer application.
    Another way to install the API Designer credentials on Mac OS X, is to set the global environment variable APIC_DESIGNER_CREDENTIALS=designer_credentials_file_path/designer_credentials.json to make it available to the API Designer application.

    After you have set the APIC_DESIGNER_CREDENTIALS environment variable, your API Designer uses these new credentials to authenticate with the management server.

  7. Launch the API Designer user interface by running the application from the location to which you extracted the contents of the toolkit compressed file.
    Note:
    • To uninstall the API Designer application on a Windows platform with a non Administrator account, complete the following steps:
      1. In Windows File Explorer, navigate to the USER_HOME\AppData\Local\Programs\api-designer folder.
      2. Run the Uninstall API Designer application application. Do not use the Add or remove programs window.
    • To uninstall the API Designer application on a Windows platform with an Administrator account, you can either run the Uninstall API Designer application application, or you can use the Add or remove programs window.

Results

The IBM API Connect toolkit CLI and, if selected, the API Designer user interface application are installed on your local system.

For information on using the API Designer user interface, see Developing your APIs and applications.

For information on using the toolkit CLI, see Using the developer toolkit command-line tool.