

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¶

Download API Controller based on your preferred platform (i.e., Mac, Windows, Linux).
Extract the downloaded archive of the CTL Tool to the desired location.
Navigate to the working directory where the executable CTL Tool 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 CTL Tool.
```
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 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.4
Build Date: 2023-08-31 06:09:23 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 <USER_HOME>/.wso2apictl/main_config.yaml file or by running the following CTL command.

apictl add-env

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

Run the following CTL command to add an environment.

Command

Linux/Unix

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>

Mac

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

Linux/Unix

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

Mac

apictl add-env -e dev --registration https://localhost:9443/client-registration/v0.15/register --apim https://localhost:9443 --token https://localhost:8243/token

Example

Linux/Unix

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

Mac

apictl add-env -e production --registration https://localhost:9444/client-registration/v0.15/register --apim https://localhost:9444 --token https://localhost:8244/token --admin https://localhost:9444/api/am/admin/v0.15 --api_list https://localhost:9444/api/am/publisher/v0.15/apis --app_list https://localhost:9444/api/am/store/v0.15/applications

Response

Response Format

Successfully added environment '<environment-name>'

Example Response

Successfully added environment 'production'

Remove an environment¶

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

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

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

List environments¶

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

Run the following CTL command to list the environments.

Command
```
apictl list envs
```
Info

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

Response

Response Format

NAME                  API MANAGER ENDPOINT      REGISTRATION ENDPOINT      TOKEN ENDPOINT
<environment-name>    <API-Manager-endpoint>    <registration-endpoint>    <token-endpoint>

Example Response

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

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

Make sure that WSO2 API Manager is started and the CTL tool is running.
For more information, see Download and Initialize the CTL Tool.
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 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 -k
```
```
apictl login dev -u admin -p admin -k
```
```
apictl login dev -username admin -password admin -k
```
- Response
  Response Format
```
Logged into '<environment-name>' environment 
```
  Example Response
```
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¶

Make sure that WSO2 API Manager is started and the CTL tool is running.
For more information, see Download and Initialize the CTL Tool.
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
```

Add APIs/Applications in an environment¶

You can add APIs and Applications via the Publisher Portal and Developer Portal accordingly. However, apictl allows you to create and deploy APIs without using the Publisher Portal. For more information on adding APIs, see Importing APIs Via Dev First Approach.

List APIs of an environment¶

Follow the instructions below to display a list of APIs in an environment using CTL:

Make sure that WSO2 API Manager is started and the CTL tool is running.
For more information, see Download and Initialize the CTL Tool.
Log in to the API Manager in the environment by following the instructions in Login to an Environment.

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¶

Follow the instructions below to display a list of applications in an environment using CTL:

Make sure that WSO2 API Manager is started and the CTL tool is running.
For more information, see Download and Initialize the CTL Tool.
Log in to the API Manager in the environment by following the instructions in Login to an Environment.

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¶

Follow the instructions below to generate a JWT/OAuth token for testing purposes using CTL in order to invoke an API by subscribing to it using the default application:

Make sure that WSO2 API Manager is started and the CTL tool is running.
For more information, see Download and Initialize the CTL Tool.
Log in to the API Manager in the environment by following the instructions in Login to an Environment.
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 defined in the <USER_HOME>/.wso2apictl/main-config.yamlfile. For information on changing the token type, see Set 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

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 should be saved.
Default : /home/.wso2apictl/exported

Top

Getting Started with WSO2 API Controller¶

Download and initialize the CTL Tool¶

Global flags for CTL Tool¶

Check the version of the CTL¶

Set mode of the CTL¶

Add an environment¶

Remove an environment¶

List environments¶

Login to an environment¶

Logout from an environment¶

Add APIs/Applications in an environment¶

List APIs of an environment¶

List applications of an environment¶

Get keys for an API¶

Set token type¶

Set HTTP request timeout¶

Set export directory¶