Setting up the API Connect toolkit

Install the toolkit that provides CLI commands and the API Designer user interface for IBM® API Connect.

About this task

With the toolkit, you can choose how you want to work with your APIs:

API Designer offers a graphical interface similar to API Manager. Because you work locally, not all API Manager features are available in API Designer.
The CLI (Command Line Interface) lets you work in a command window instead of using the graphical interface.

Setting up the toolkit involves the following tasks:

Downloading the toolkit
Logging in to the toolkit

Downloading the toolkit

About this task

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 + Designer option, an executable file for launching the API Designer application.

Procedure

Download the toolkit from API Manager in IBM API Connect.
1. Log in to API Manager using your IBMid.
2. On the API Manager home page, click the Tools for download link.
3. In the "Step 1: Download toolkit" section of the Install API Connect Toolkit window, select the type of package you want to download and click the link for your operating system.
  - CLI: provides a command line environment for working with IBM API Connect.
  - CLI + Designer: provides a command-line environment for working with IBM API Connect, plus the API Designer user interface.
In the "Step 2: Download credentials" section, download both credentials files:
1. Click the Download option for Credential and save the credentials.json file to your local file system.
2. Click the Download option for the API Designer Credentials and save the designer_credentials.json file to your local file system.
On your computer, locate the downloaded toolkit-compressed file and extract the contents to a folder of your choice.
The contents of the file depend on your chosen toolkit option and platform, as follows:
- 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.
  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 + Designer option.
- The api_designer-platform file is the API Designer user interface application for the specified platform.
Run the CLI.
- For the Mac OSX 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 the toolkit CLI reference documentation.
- For the Windows platform, complete the following steps:
  1. Open a command prompt 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 the toolkit CLI reference documentation.
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.
Install the toolkit credentials:
Install the toolkit credentials by opening a terminal window (or Windows command prompt) and running the following command:
```
apic client-creds:set <toolkit_credentials_file_path>/credentials.json
```
where <credentials_file_path> is the location where you downloaded the toolkit credentials JSON file. The toolkit uses these new credentials to authenticate with the server hosting the API Manager.
Install the API Designer credentials:
Install the API Designer credentials by setting the APIC_DESIGNER_CREDENTIALS environment variable to the credentials download location, using the mechanism appropriate for your operating system.

Windows: create an environment variable using one of the following methods.
- Create a permanent environment variable so that you can start API Designer from any location on your computer:
  1. Open the Environment Variables page: Click Start > Settings > System and in the "Related Settings" section of the page, click Advanced System Settings.
  2. On the Advanced tab of the System Properties dialog box, click Environment Variables.
  3. In the "User variables" section, click New and create an environment variables with the following settings:
    - Variable: APIC_DESIGNER_CREDENTIALS
    - Value: <designer_credentials_file_path>\designer_credentials.json where <designer_credentials_file_path> is the location where you stored the designer_credentials.json file.
  4. Click OK to save the new environment variable, and then exit the dialog box.
- Create a temporary environment variable that will only be used while you are running the API Designer application.
  The following steps must be performed every time you start API Designer:
  1. Open the Windows command prompt.
  2. Run the following command to set the temporary environment variable:
```
set APIC_DESIGNER_CREDENTIALS=<designer_credentials_file_path>\designer_credentials.json
```
    where <designer_credentials_file_path> is the location where you stored the designer_credentials.json file.
    
    Note: Leave the command prompt open for the next step. You must set the temporary variable and start the API Designer within the same Windows command session.
  3. Now run the following command to start API Designer:
```
C:\"Program Files\API Designer\API Designer.exe"
```
    By default, API Designer is installed in the C:\"Program Files\API Designer folder as shown in the example. If you installed it into a different location, use your own location in the command. Note that the path and file name are enclosed in quotation marks because they contain spaces.
Mac OS X: create an environment variable using one of the following methods:
- Set a permanent global environment variable by running the following command:
```
launchctl setenv APIC_DESIGNER_CREDENTIALS <designer_credentials_file_path>/designer_credentials.json
```
  where <designer_credentials_file_path> is the location where you stored the API Designer credentials JSON file.
- Pass in a temporary environment variable while starting API Designer from the command line.
  With this method, you must run the following command every time you start API Designer:
```
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.

Logging in to the toolkit

About this task

Procedure

Clear the toolkit credentials from any previous login by running the following command:
```
apic client-creds:clear
```
The response confirms that the credentials were deleted:
```
Deleted client credentials
```
Clearing the credentials ensures that you do not inadvertently log in with the wrong set of credentials (for example, from a different product release or environment). There is no need to clear the API Designer credentials.
Set the credentials that you want to use now by running the following command:
```
apic client-creds:set <path_to_credentials>/credential.json
```
where <path_to_credentials> is the location of the credential.json file that you want to use. For example:
```
apic client-creds:set /Users/local_user/credential.json
```
Log in by running the following command:
```
apic login --server <platform-api-host-name> --sso
```
Where <platform-api-host-name> is the hostname portion URL of server that hosts the API Manager (the "management server"). To determine the hostname, open API Manager in a browser and copy the hostname from the URL in the address bar (beginning after "https://" and ending before "/manager") as shown in the following example:
```
https://platform-api.us-east-1.d-r01.apic.cloud.ibm.com/manager
```
When the toolkit prompts for the context, type provider and press Enter:
```
Context? provider
```
A confirmation message displays to indicate that you are now logged in to the API Manager server.

To log out, run the following command:
```
apic logout --server <api-manager-host-name>
```
The response confirms your logout:
```
Successfully logged out of <api-manager-host-name>
```