

Getting Started with ESB API Controller (apictl)¶

ESB API Controller (apictl) is a command-line tool providing the capability to move APIs, API Products, and Applications across environments and to perform CI/CD operations. It can also be used to perform these same tasks on a Kubernetes deployment. Furthermore, it can perform ESB Micro Integrator (ESB MI) server specific operations such as monitoring Synapse artifacts and performing MI management/administrative tasks from the command line.

Download and initialize the apictl¶

Download apictl based on your preferred platform (i.e., Mac, Windows, Linux).
Extract the downloaded archive of the apictl to the desired location.
Navigate to the working directory where the executable apictl resides.
Add the current working directory to your system's $PATH variable to be able to access the executable from anywhere.
Execute the following command to start the apictl.

Warn

If you have previously used an apictl old version, backup and remove /home/<user>/.wso2apictl directory and reconfigure the environments using the commands as explained below in Add an environment section.
```
apictl
```
The directory structure for the configuration files (<USER_HOME>/.wso2apictl) will be created upon the execution of the apictl command.
Tip

If you want to change the default location for the .wso2apictl directory, set an environment variable (APICTL_CONFIG_DIR) as follows with the path for the desired location.
Linux/Mac
```
export APICTL_CONFIG_DIR="/home/wso2user/CLI"
```
Windows
```
set APICTL_CONFIG_DIR=C:\Users\wso2user\CLI
```
Tip

For further instructions, execute the following command.
```
apictl --help
```

Global flags for apictl¶

The following are some global flags that you can use with any apictl command.

--verbose
    Enable verbose logs (Provides more information on execution)
--insecure, -k
    Allow connections to SSL sites without certs
--help, -h
    Display information and example usage of a command

Check the version of the apictl¶

Run the following apictl command to check the version.

Command
```
apictl version
```

Response

Version: 4.2.0
Build Date: 2023-03-11 11:14:10 UTC

Note

Set mode of apictl

From the apictl 4.0.0 onwards the flag (--mode) which was used to set the mode of apictl has been deprecated. Now, you do not need to set the mode of apictl, because if you want to execute Kubernetes based commads, you just need to add the k8s keyword after apictl keyword. (Example: apictl k8s add api). By default apictl will execute the commands in the default mode (which means if you did not use k8s keyword).

You can still use the mode flag as explained below if you need it, but it will be removed in the future.

Command

apictl set --mode <mode>

Example

apictl set --mode default

apictl set --mode kubernetes

The allowed modes are default and kubernetes.

Set proxy environment variables for apictl¶

You can set proxy related HTTP_PROXY, HTTPS_PROXY, http_proxy, and https_proxy standard environment variables, with or without basic authentication as shown below to send the requests initiated from CTL via a proxy server. After one of the following environment variables is set in your environment where CTL is used, all the requests will go through the proxy server specified.

Formats

Without Basic Authentication

export HTTP_PROXY="http://<host-name>:<port>"

export HTTPS_PROXY="https://<host-name>:<port>"

export http_proxy="http://<host-name>:<port>"

export https_proxy="https://<host-name>:<port>"

With Basic Authentication

export HTTP_PROXY="http://<username>:<password>@<host-name>:<port>"

export HTTPS_PROXY="https://<username>:<password>@<host-name>:<port>"

export http_proxy="http://<username>:<password>@<host-name>:<port>"

export https_proxy="https://<username>:<password>@<host-name>:<port>"

Examples

Without Basic Authentication

export HTTP_PROXY="http://localhost:3128"

export HTTPS_PROXY="https://localhost:3128"

export http_proxy="http://localhost:3128"

export https_proxy="https://localhost:3128"

With Basic Authentication

export HTTP_PROXY="http://testuser:password@localhost:3128"

export HTTPS_PROXY="https://testuser:password@localhost:3128"

export http_proxy="http://testuser:password@localhost:3128"

export https_proxy="https://testuser:password@localhost:3128"

Add an environment¶

You can add environments by either manually editing the <USER_HOME>/.wso2apictl/main_config.yaml file or by running the following apictl command.

apictl add env <environment-name>

Make sure that the MWARE ESB 4.2.0 version is started and that the 4.2.0 version of apictl is set up.
For more information, see Download and Initialize the apictl.

Run the following apictl command to add an environment.

Command
Linux/Unix
```
apictl add env <environment-name> \
               --registration <client-registration-endpoint> \
               --apim <API-Manager-endpoint> \
               --token <token-endpoint> \
               --admin <admin-REST-API-endpoint> \
               --publisher <publisher-portal-endpoint> \
               --devportal <developer-portal-endpoint> \
               --mi <mi-management-endpoint>
```
Mac/Windows
```
apictl add env <environment-name> --registration <client-registration-endpoint> --apim <API-Manager-endpoint> --token <token-endpoint> --admin <admin-REST-API-endpoint> --publisher <publisher-portal-endpoint> --devportal <developer-portal-endpoint> --mi <mi-management-endpoint>
```
Info

Flags:

To add a MWARE ESB
- Required :
  (either)
  --apim : ESB endpoint for the environments
  OR (the following 4)
  --registration : Registration endpoint for the environment
  --admin : Admin endpoint for the environment
  --publisher : Publisher Portal endpoint for the environment
  --devportal : Developer Portal endpoint for the environment
- Optional :
  --token : Token endpoint for the environment
To add a ESB MI
- Required :
  --mi : Management endpoint of the Micro Integrator
Tip

When adding an environment, when the optional flags are not given, apictl will automatically derive those from --apim flag value.

Note

You can either provide only the flag --apim , or all the other 4 flags (--registration, --publisher, --devportal, --admin) without providing --apim flag. If you are omitting any of --registration, --publisher, --devportal, --admin flags, you need to specify --apim flag with the MWARE ESB endpoint. In both of the above cases --token flag is optional and can be used to provide a user-preferred token endpoint. You can use the --mi flag to add a Micro Integrator instance to an environment.

Adding a MWARE ESB to an environment using --apim flag

Example

Linux/Unix

apictl add env dev \
            --apim https://localhost:9443

Mac/Windows

apictl add env dev --apim https://localhost:9443

Adding a MWARE ESB to an environment using --registration, --publisher, --devportal, --admin flags

Example

Linux/Unix

apictl add env production \
            --registration https://idp.com:9444 \
            --admin https://apim.com:9444 \
            --publisher https://apim.com:9444 \
            --devportal https://apps.com:9444 \
            --token https://gw.com:8244/token

Mac/Windows

apictl add env production --registration https://idp.com:9444  --admin https://apim.com:9444 --publisher https://apim.com:9444 --devportal https://apps.com:9444 --token https://gw.com:8244/token

Adding a MWARE ESB to an environment using some of the --registration, --publisher, --devportal, --admin flags along with --apim flag

Example

Linux/Unix

apictl add env production \
            --registration https://idp.com:9444 \
            --apim https://apim.com:9444 \
            --token https://gw.com:8244/token

Mac/Windows

apictl add env production --registration https://idp.com:9444 --apim https://apim.com:9444 --token https://gw.com:8244/token

Adding a ESB MI to an environment using --mi flag

Example

Linux/Unix

apictl add env dev \
            --mi https://localhost:9164

Mac/Windows

apictl add env dev --mi https://localhost:9164

Adding both MWARE ESB and ESB MI to an environment
Example
Linux/Unix
```
apictl add env test \
            --apim https://localhost:9443 \
            --mi https://localhost:9164
```
Mac/Windows
```
apictl add env test --apim https://localhost:9443 --mi https://localhost:9164
```
Note

apictl add-env command has been deprecated from apictl 4.0.0 onwards. Instead, use apictl add env as shown above.

Response

Response Format

Successfully added environment '<environment-name>'

Example Response

Successfully added environment 'production'

Remove an environment¶

Make sure that the MWARE ESB 4.2.0 version is started and that the 4.2.0 version of apictl is set up.
For more information, see Download and Initialize the apictl.

Run the following apictl command to remove an environment.

Command

apictl remove env <environment-name>

Example

apictl remove env production

Response

Response Format

Successfully removed environment '<environment-name>'
Execute 'apictl add env --help' to see how to add a new environment

Example Response

Successfully removed environment 'production'
Execute 'apictl add env --help' to see how to add a new environment

Get environments¶

Make sure that the MWARE ESB 4.2.0 version is started and that the 4.2.0 version of apictl is set up.
For more information, see Download and Initialize the apictl.

Run the following apictl command to list the environments.

Command
```
apictl get envs
```
Info

Flags:
- Optional :
  --format : pretty-print environments using Go templates

Response

Response Format

NAME                  API MANAGER ENDPOINT      REGISTRATION ENDPOINT      TOKEN ENDPOINT     PUBLISHER ENDPOINT       DEVPORTAL ENDPOINT       ADMIN ENDPOINT          MI MANAGEMENT ENDPOINT
<environment-name>    <APIM-endpoint>           <registration-endpoint>    <token-endpoint>   <Publisher-endpoint>     <DevPortal-endpoint>     <admmin-endpoint>       <mi-management-endpoint>

Example Response

NAME         API MANAGER ENDPOINT     REGISTRATION ENDPOINT    TOKEN ENDPOINT                  PUBLISHER ENDPOINT       DEVPORTAL ENDPOINT       ADMIN ENDPOINT             MI MANAGEMENT ENDPOINT
dev          https://localhost:9443   https://localhost:9443   https://localhost:8243/token    https://localhost:9443   https://localhost:9443   https://localhost:9443
production   https://localhost:9444   https://localhost:9444   https://localhost:8244/token    https://localhost:9444   https://localhost:9444   https://localhost:9444     https://localhost:9164
dev-mi                                                                                                                                                                      https://localhost:9164

Note

Output of the get envs command can be formatted with Go Templates. For more information on formatting the get commands, see Formatting the outputs of get commands.

Note

apictl list envs command has been deprecated from the apictl 4.0.0 onwards. Instead use apictl get envs as shown above.

After adding an environment, you can log in to the MWARE ESB instance in that environment using credentials.

Make sure that the MWARE ESB 4.2.0 version is started and that the 4.2.0 version of apictl is set up.
For more information, see Download and Initialize the apictl.
Run any of the following apictl commands to log in to the environment.
- Command
```
apictl login <environment-name> 
```
```
apictl login <environment-name> -u <username> 
```
```
apictl login <environment-name> -u <username> -p <password> 
```
  Tip
  
  If you run apictl login <environment-name> you are prompted to provide both the username and the password. If you run apictl login <environment-name> --username <username>, you are prompted to provide the password.
  Info
  
  Flags:
  - Optional :
    --username or -u : Username for login
    --password or -p : Password for login
    --password-stdin : Get password from stdin
  Example
```
apictl login dev 
```
```
apictl login dev -u admin -p admin 
```
```
apictl login dev --username admin --password admin 
```
- Response
  Response Format
```
Logged into '<environment-name>' environment 
```
  Example Response
```
Logged into dev environment
```
Warning

Using --password in apictl is not secure. You can use --password-stdin instead. For example,
```
cat ~/.mypassword | ./apictl login dev --username admin --password-stdin 
```

Logout from an environment¶

Make sure that the MWARE ESB 4.2.0 version is started and that the 4.2.0 version of apictl is set up.
For more information, see Download and Initialize the apictl.
Run the following command to log out from the current session of the MWARE ESB environment.
- Command
```
apictl logout <environment-name>
```
  Example
```
apictl logout dev
```

Set HTTP request timeout¶

Run the following apictl command to set the HTTP request timeout.

Command
```
apictl set --http-request-timeout <http-request-timeout>
```
Example
```
apictl set --http-request-timeout 10000
```
Info

Flags:
- Required :
  --http-request-timeout : Timeout for HTTP Client (default 10000)

Set TLS renegotiation mode¶

By default, TLS renegotiation is disabled for the apictl. However, the TLS renegotiation mode can be configured by running the following command, which will be applied globally to all subsequent TLS connections established by apictl.

Command
```
apictl set --tls-renegotiation-mode <never|once|freely>
```
Example
```
apictl set --tls-renegotiation-mode freely
```
Info

Flags:
- Required :
  --tls-renegotiation-mode
Allowed values for this flag are,

never: Disable TLS renegotiation

once: Allow TLS renegotiation once

freely: Allow unrestricted TLS renegotiation

Set export directory¶

Run the following apictl command to change the default location of the export directory.

Command
```
apictl set --export-directory <export-directory-path>
```
Example
Linux/Mac
```
apictl set --export-directory /home/user/exported-apis
```
Windows
```
apictl set --export-directoty C:\Documents\exported
```
Info

Flags:
- Required :
  --export-directory: Path to directory where APIs, API Products, and Applications should be saved.
  Default : /home/.wso2apictl/exported

Import SSL certificates for Secure HTTP communication with MWARE ESB¶

Different environments of MWARE ESB can have different SSL certificates for secure HTTP communications. The default certificate of MWARE ESB is a self-signed certificate and in production environments, it is advised to use a different certificate than the default.

If the certificate is the default ESB certificate or a CA-signed certificate of a CA (Certificate Authority) trusted by the OS, these certificates will be imported by default to apictl. If the CA or the certificate is new or does not get imported by default, you can add the certificate to the certs directory found in APICTL_CONFIG_DIR/.wso2apictl. (The default location of the certs directory is /home/.wso2apictl/certs)

The certificates added to this directory will be imported whenever an action is performed with apictl. Any DER or PEM encoded certificate with the file extensions of *.pem, *.crt or *.cer can be used with apictl.

Info

If you are using Windows, CA certs will not be imported by default and have to be added to the certs directory.

Top

Getting Started with ESB API Controller (apictl)¶

Download and initialize the apictl¶

Global flags for apictl¶

Check the version of the apictl¶

Set proxy environment variables for apictl¶

Add an environment¶

Remove an environment¶

Get environments¶

Login to an environment¶

Logout from an environment¶

Set HTTP request timeout¶

Set TLS renegotiation mode¶

Set export directory¶

Import SSL certificates for Secure HTTP communication with MWARE ESB¶