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

  1. Download apictl based on your preferred platform (i.e., Mac, Windows, Linux).

  2. Extract the downloaded archive of the apictl to the desired location.

  3. Navigate to the working directory where the executable apictl resides.
  4. Add the current working directory to your system's $PATH variable to be able to access the executable from anywhere.
  5. 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.

    export APICTL_CONFIG_DIR="/home/wso2user/CLI"
    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

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

    export HTTP_PROXY="http://localhost:3128"
    
    export HTTPS_PROXY="https://localhost:3128"
    
    export http_proxy="http://localhost:3128"
    
    export https_proxy="https://localhost:3128"
    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>
  1. 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.
  2. Run the following apictl command to add an environment.

    • Command

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

      apictl add env dev \
                  --apim https://localhost:9443 
      apictl add env dev --apim https://localhost:9443 
    • Adding a MWARE ESB to an environment using --registration, --publisher, --devportal, --admin flags

      Example

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

      apictl add env production \
                  --registration https://idp.com:9444 \
                  --apim https://apim.com:9444 \
                  --token https://gw.com:8244/token
      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

      apictl add env dev \
                  --mi https://localhost:9164
      apictl add env dev --mi https://localhost:9164
    • Adding both MWARE ESB and ESB MI to an environment

      Example

      apictl add env test \
                  --apim https://localhost:9443 \
                  --mi https://localhost:9164
      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

      Successfully added environment '<environment-name>'
      Successfully added environment 'production'

Remove an environment

  1. 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.
  2. Run the following apictl command to remove an environment.

    • Command

      apictl remove env <environment-name> 

      Example

      apictl remove env production
    • Response

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

Get environments

  1. 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.
  2. Run the following apictl command to list the environments.

    • Command

      apictl get envs

      Info

      Flags:

      • Optional :
        --format : pretty-print environments using Go templates
    • Response

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

Login to an environment

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

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

      Logged into '<environment-name>' environment 
      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

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

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

    apictl set --export-directory /home/user/exported-apis
    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