Skip to content

Getting Started with WSO2 API Controller

WSO2 API Controller(CTL) is a command-line tool for managing API Manager environments, listing apis and applications, creating API projects, importing and exporting APIs and applications, generating tokens for testing purposes, etc.

Download and Initialize the CTL Tool

  1. Navigate to the API Management Tooling page - https://wso2.com/api-management/tooling/
  2. Click Download button under Dev-Ops Tooling according to your preferred platform (i.e., Mac, Windows, Linux).
  3. Extract the downloaded archive of the CTL Tool to the desired location.

  4. Navigate to the working directory where the executable CTL Tool resides.

  5. Execute the following command to start the CTL Tool.

    ./apictl
    The directory structure for the configuration files ( $HOME/.wso2apictl ) will be created upon the execution of the apictl command.

  6. Add the location of the extracted folder to your system's $PATH variable to be able to access the executable from anywhere.

    Tip

    For further instructions execute the following command.

    apictl --help

Global Flags for CTL Tool

The following are some global flags that you can use with any CTL tool 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 CTL

Run the following CTL command to check the version of the CTL.

  • Command
    apictl version
  • Response

    Version: 3.0.0
    Build Date: 2019-10-28 13:22:12 UTC

Set Mode of the CTL

Run the following CTL command to set the mode of the CTL. The allowed modes are default and kubernetes.

  • Command

    apictl set mode <mode>

    Example

    apictl set mode default
    apictl set mode kubernetes

Add an Environment

You can add environments by either manually editing the $HOME/.wso2apictl/main_config.yaml file or by running the following CTL command.

apictl add-env
  1. Make sure that the WSO2 API Manager is started and that the CTL tool is running.
    For more information, visit Download and Initialize the CTL Tool.
  2. Run the following CTL command to add an environment.

    • Command

      apictl add-env -e <environment-name> \
                      --registration <registration-endpoint> \
                      --apim <API-Manager-endpoint> \
                      --token <token-endpoint> \
                      --admin <admin-REST-API-endpoint> \
                      --api_list <API-listing-REST-API-endpoint> \
                      --app_list <application-listing-REST-API-endpoint>
      apictl add-env -e <environment-name> --registration <registration-endpoint> --apim <API-Manager-endpoint> --token <token-endpoint> --admin <admin-REST-API-endpoint> --api_list <API-listing-REST-API-endpoint> --app_list <application-listing-REST-API-endpoint>

      Info

      Flags:

      • Required :
        --environment or -e : Name of the environment to be added
        --registration : Registration endpoint for the environment
        --token : Token endpoint for the environment
        --apim : API Manager endpoint for the environments

      • Optional :
        --admin : Admin endpoint for the environment
        --api_list : API List endpoint for the environment
        --app_list : Application List endpoint for the environment

      Tip

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

      Example

      apictl add-env -e dev \
                  --registration https://localhost:9444/client-registration/v0.15/register \
                  --apim https://localhost:9444 \
                  --token https://localhost:8244/token \
      ./apictl add-env -e dev --registration https://localhost:9444/client-registration/v0.15/register --apim https://localhost:9444 --token https://localhost:8244/token

      Example

      apictl add-env -e production \
                  --registration https://localhost:9443/client-registration/v0.15/register \
                  --apim https://localhost:9443 \
                  --token https://localhost:8243/token \
                  --admin https://localhost:9443/api/am/admin/v0.15 \
                  --api_list https://localhost:9443/api/am/publisher/v0.15/apis \
                  --app_list https://localhost:9443/api/am/store/v0.15/applications
      apictl add-env -e production --registration https://localhost:9443/client-registration/v0.15/register --apim https://localhost:9443 --token https://localhost:8243/token --admin https://localhost:9443/api/am/admin/v0.15 --api_list https://localhost:9443/api/am/publisher/v0.15/apis --app_list https://localhost:9443/api/am/store/v0.15/applications
    • Response

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

Remove an Environment

  1. Make sure that WSO2 API Manager is started and the CTL tool is running.
    For more information, visit Download and Initialize the CTL Tool.
  2. Run the following CTL command to remove an environment.

    • Command

      apictl remove-env -e <environment-name> 

      Info

      Flags:

      • Required :
        --environment or -e: Name of the environment to be removed

      Example

      apictl remove-env --environment 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

List Environments

  1. Make sure that WSO2 API Manager is started and the CTL tool is running.
    For more information, visit Download and Initialize the CTL Tool.
  2. Run the following CTL command to list the environments.

    • Command

      apictl list envs

      Info

      Flags:

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

      NAME                  API MANAGER ENDPOINT      REGISTRATION ENDPOINT      TOKEN ENDPOINT
      <environment-name>    <API-Manager-endpoint>    <registration-endpoint>    <token-endpoint>
      NAME         API MANAGER ENDPOINT     REGISTRATION ENDPOINT                                       TOKEN ENDPOINT
      dev          https://localhost:9443   https://localhost:9443/client-registration/v0.15/register   https://localhost:8243/token
      production   https://localhost:9444   https://localhost:9444/client-registration/v0.15/register   https://localhost:8244/token   
      

Login to an Environment

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

  1. Make sure that WSO2 API Manager is started and the CTL tool is running.
    For more information, visit Download and Initialize the CTL Tool.
  2. Run any of the following CTL commands to log in to the environment.

    • Command

      apictl login <environment-name> -k
      apictl login <environment-name> -u <username> -k
      apictl login <environment-name> -u <username> -p <password> -k

      Tip

      If you run apictl login <environment-name> you are prompt to provide both username and password.
      If you run apictl login <environment-name> --username <username>, you are prompt to provide 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 -k
      apictl login dev -u admin -p admin -k

      apictl login dev -username admin -password admin -k
    • Response

      Logged into '<environment-name>' environment 
      Logged into dev environment

    Warning

    Using --password in CTL is not secure. You can use --password-stdin instead. For example,

    cat ~/.mypassword | ./apictl login dev --username admin --password-stdin -k

Logout from an Environment

  1. Make sure that WSO2 API Manager is started and the CTL tool is running.
    For more information, visit Download and Initialize the CTL Tool.

  2. Run the following command to log out from the current session of the API Manager environment.

    • Command

      apictl logout <environment-name>

      Example

      apictl logout dev

List APIs of an Environment

By following the below steps, you can display a list of APIs in an environment using CTL.

  1. Make sure that WSO2 API Manager is started and the CTL tool is running.
    For more information, visit Download and Initialize the CTL Tool.
  2. Log in to the API Manager in the environment by following steps in Login to an Environment.
  3. Run any of the following CTL commands to list the APIs.

    • Command

      apictl list apis -e <environment> -k
      apictl list apis --environment <environment> --insecure
      apictl list apis --environment <environment> --query <API search query> --insecure

      Info

      Flags:

      • Required :
        --environment or -e : Environment to be searched
      • Optional :
        --query or -q : Search query pattern

      Example

      apictl list apis -e dev -k
      apictl list apis --environment production --insecure
      apictl list apis --environment production --query "provider:Alice name:PizzaShackAPI" --insecure

    • Response

      ID                                     NAME                VERSION             CONTEXT             STATUS              PROVIDER
      12d6e73c-778d-45ac-b57d-117c6c5092a4   PhoneVerification   1.0                 /phoneverify        PUBLISHED           admin
      91fe87c3-f0d7-4c35-81f5-0e0e42d8e19f   PizzaShackAPI       2.0.0               /pizzashack         CREATED             Alice

List Applications of an Environment

You can display a list of Applications in an environment using CTL.

  1. Make sure that WSO2 API Manager is started and the CTL tool is running.
    For more information, visit Download and Initialize the CTL Tool.
  2. Log in to the API Manager in the environment by following steps in Login to an Environment.
  3. Run any of the following CTL commands to list the Applications.

    • Command

      apictl list apps -e <environment> -k
      apictl list apps --environment <environment> --insecure
      apictl list apps --environment <environment> --owner <application owner> --insecure

      Info

      Flags:

      • Required :
        --environment or -e : Environment to be searched
      • Optional :
        --owner or -o : Owner of the Application

      Example

      apictl list apps -e dev -k
      apictl list apps --environment production --insecure
      apictl list apps --environment production --owner sampleUser --insecure

    • Response

      ID                                     NAME                OWNER       STATUS     GROUP ID
      29b4fcc6-05a4-42a7-aa64-f1a1b8a7b979   DefaultApplication  admin       APPROVED 
      
      36d51e55-3f1e-4f85-86ee-8fe73b0c8adff  SampleApplication   sampleUser  APPROVED   orgA

Get Keys for an API

For testing purposes, the CTL tool allows generating a JWT/OAuth token to invoke an API by subscribing from a default application.

  1. Make sure that WSO2 API Manager is started and the CTL tool is running.
    For more information, visit Download and Initialize the CTL Tool.
  2. Log in to the API Manager in the environment by following steps in Login to an Environment.
  3. Run any of the following CTL commands to get keys for the API.

    • Command
    apictl get-keys -n <API name> -v <API version> -r <API provider> -e <environment> -k
    apictl get-keys --name <API name> --version <API version> --provider <API provider> --environment <environment> -k

    Example

    apictl get-keys -n PizzaShackAPI -v 1.0.0 -r admin -e dev -k

    Info

    Flags:

    • Required :
      --environment or -e : Key generation environment
      --name or -n : API to enerate keys for
      --version or -v : Version of the API
      --provider or -r : Provider of the API

    Info

    Upon running the above command, the CTL tool will create a default application in the environment, subscribe to the API and generate keys based on the token type given in $HOME/.wso2apictl/main-config.yaml. Refer Set Token Type to change the token type.

Set Token Type

Run the following CTL command to set the token type of the default apictl application.

  • Command

    apictl set --token-type <token type>

    Example

    apictl set --token-type JWT
    apictl set --token-type OAuth

    Info

    Flags:

    • Required :
      --token-type or -t : Type of the token to be generated

Set HTTP Request Timeout

Run the following CTL 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 Export Directory

Run the following CTL 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 should be saved.
      Default : /home/.wso2apictl/exported
Top