

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.

Warn

From API Manager Tooling 3.1.0 version onwards, the names of the endpoints have been modified and this causes changing the syntax in /home/<user>/.wso2apictl/main_config.yaml file. If you have an older file, you'll get an error while executing the apictl commands due to this. To avoid that, backup and remove /home/<user>/.wso2apictl/main_config.yaml file and reconfigure the environments using new 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 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.1.5
Build Date: 2022-06-08 17:22:46 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 3.1.0 version is started and that the 3.1.0 version of APTCTL 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 <client-registration-endpoint> \
                --apim <API-Manager-endpoint> \
                --token <token-endpoint> \
                --admin <admin-REST-API-endpoint> \
                --publisher <publisher-portal-endpoint> \
                --devportal <developer-portal-endpoint>

Mac/Windows

apictl add-env -e <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>

Info

Flags:

Required :

`--environment` or `-e` : Name of the environment to be added   
`--token` : Token endpoint for the environment
AND (either)
`--apim` : API Manager endpoint for the environments
OR (the following 4)
`--registration` : Registration endpoint for the environment 
`--admin` : Admin endpoint for the environment  
`--publisher` : Publisher endpoint for the environment  
`--devportal` : Developer Portal 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.

Note

The flags --environment (-e) and --token are mandatory. You can either provide only the 2 flags --apim and --token, or all the other 5 flags (--registration, --publisher, --devportal, --admin, --token) without providing --apim flag. If you are omitting any of --registration, --publisher, --devportal, --admin flags, you need to specify --apim flag with the API Manager endpoint.

Example

Linux/Unix

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

Mac/Windows

apictl add-env -e dev --apim https://localhost:9443 --token https://localhost:8243/token

Example

Linux/Unix

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

Mac/Windows

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

Example

Linux/Unix

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

Mac/Windows

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

Response

Response Format

Successfully added environment '<environment-name>'

Example Response

Successfully added environment 'production'

Remove an environment¶

Make sure that the WSO2 API Manager 3.1.0 version is started and that the 3.1.0 version of APTCTL 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 <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

List environments¶

Make sure that the WSO2 API Manager 3.1.0 version is started and that the 3.1.0 version of APTCTL 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     PUBLISHER ENDPOINT       DEVPORTAL ENDPOINT       ADMIN ENDPOINT
<environment-name>    <APIM-endpoint>           <registration-endpoint>    <token-endpoint>   <Publisher-endpoint>     <DevPortal-endpoint>     <admmin-endpoint>

Example Response

NAME         API MANAGER ENDPOINT     REGISTRATION ENDPOINT    TOKEN ENDPOINT                  PUBLISHER ENDPOINT       DEVPORTAL ENDPOINT       ADMIN 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

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

Make sure that the WSO2 API Manager 3.1.0 version is started and that the 3.1.0 version of APTCTL 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 the WSO2 API Manager 3.1.0 version is started and that the 3.1.0 version of APTCTL 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/Applications in an environment¶

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

Make sure that the WSO2 API Manager 3.1.0 version is started and that the 3.1.0 version of APTCTL 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 the corresponding CTL command below to list APIs/API Products/Applications in an environment.
1. List APIs in an environment.
  - 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
      --limit or -l : Maximum number of apis to return (Default 25) --format : pretty-print environments using templates
    Example
```
apictl list apis -e dev -k
```
```
apictl list apis --environment production --limit 15 --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
```
    Tip
    
    When using the apictl list apis -e dev command, -q or --query optional flag can be used to search for APIs. You can search in attributes by using a : modifier. Supported attribute modifiers are name, version, provider, context, status, description, subcontext, doc and label. You can also use combined modifiers.
    Example:
    - provider:wso2 will match an API if the provider of the API contains wso2.
    - 'provider:"wso2"' will match an API if the provider of the API is exactly wso2.
    - status:PUBLISHED will match an API if the API is in PUBLISHED state.
    - label:external will match an API if it contains a Microgateway label called "external".
    - name:pizzashack version:v1 will match an API if the name of the API is pizzashack and version is v1.
    If no advanced attribute modifier has been specified, the API names containing the search term will be returned as a result.
2. List Applications in an environment.
  - 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
      --limit or -l : Maximum number of applications to return (Default 25)
    Example
```
apictl list apps -e dev -k
```
```
apictl list apps --environment production --insecure
```
```
apictl list apps --environment production --owner sampleUser --limit 15 --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
```
    Tip
    
    When using the apictl list apps -e dev command, you can either specify -o (--owner) flag or not.
    - When someone has invoked the command without specifying the owner flag, it will list all the applications in that environment which belongs to the tenant that the currently logged in user belongs.
    - When someone has invoked the command by specifying the owner flag, it will list all the applications belongs to that particular owner in that environment.

Delete an API/Application in an environment¶

Follow the instructions below to delete an API/API Product/Application in an environment using CTL:

Make sure that the WSO2 API Manager 3.1.0 version is started and that the 3.1.1 version of APTCTL is running.
For more information, see Download and Initialize the CTL Tool.

Note

Note that you need to have the APICTL version 3.1.1 or higher to use this feature.
Log in to the API Manager in the environment by following the instructions in Login to an Environment.

Run the corresponding CTL command below to delete an API/API Product/Application in an environment.

Delete an API in an environment.

Command

apictl delete api -n <API name> -v <API version> -e <environment> -k

apictl delete api --name <API name> --version <API version> --environment <environment> --insecure

apictl delete api --name <API name> --version <API version> --environment <environment> --provider <API provider> --insecure

Info

Flags:

Required :
--environment or -e : Environment from which the API should be deleted
--name or -n : Name of the API to be deleted
--version or -v : Version of the API to be deleted
Optional :
--provider or -r : Provider of the API to be deleted

Example

apictl delete api -n PizzaShackAPI -v 1.0.0 -e dev -k

apictl delete api --name PizzaShackAPI --version 1.0.0 --environment production --insecure

apictl delete api --name PizzaShackAPI --version 1.0.0 --environment production --provider Alice --insecure

Response
```
PizzaShackAPI API deleted successfully!
```

Delete an Application in an environment.

Command

apictl delete app -n <application name> -e <environment> -k

apictl delete app -name <application name> --environment <environment> --insecure

apictl delete app --name <application name> --environment <environment> --owner <application owner> --insecure

Info

Flags:

Required :
--environment or -e : Environment from which the Application should be deleted
--name or -n : Name of the Application to be deleted
Optional :
--owner or -o : Owner of the Application to be deleted

Example

apictl delete app -n DefaultApplication -e dev -k

apictl delete app --name DefaultApplication --environment production --insecure

apictl delete app --name DefaultApplication --environment production --owner sampleUser --insecure

Response

DefaultApplication Application deleted successfully!

Change status of an API in an environment¶

Follow the instructions below to change the status of an API in an environment using CTL:

Make sure that the WSO2 API Manager 3.1.0 version is started and that the 3.1.1 version of APTCTL is running.
For more information, see Download and Initialize the CTL Tool.

Note

Note that you need to have the APICTL version 3.1.1 or higher to use this feature.
Log in to the API Manager in the environment by following the instructions in Login to an Environment.

Run the corresponding CTL command below to change the status of an API in an environment.

Command

apictl change-status api -a <Action> -n <API name> -v <API version> -e <environment> -k

apictl change-status api --action <Action> --name <API name> --version <API version> --environment <environment> --insecure

apictl change-status api --action <Action> --name <API name> --version <API version> --environment <environment> --provider <API provider> --insecure

Info

Flags:

Required :
--environment or -e : The environment that the command is executed on
--name or -n : The name of the respective API --version or -v : The version of the respective API --action or -a : The action to be taken to change the status of the API
Optional :
--provider or -r : The provider of the respective API

Example

apictl change-status api -a Publish -n PizzaShackAPI -v 1.0.0 -e dev -k

apictl change-status api --action Publish --name PizzaShackAPI --version 1.0.0 --environment production --insecure

apictl change-status api --action Publish --name PizzaShackAPI --version 1.0.0 --environment production --provider Alice --insecure

Response

PizzaShackAPI API state changed successfully!

Info

Supported action values : Publish, Deploy as a Prototype, Demote to Created, Demote to Prototyped, Block, Deprecate, Re-Publish, Retire. Note that the Re-publish action is available only after calling Block action.

Formatting the outputs of list¶

Output of list envs, list apis and list apps can be formatted with Go Templates.

Available formatting options¶

Name	Usage	Example
table	This is the default format and the output is displayed as a table	`--format "table {{.Name}}\t{{.Id}}"`
json	Output is formatted as JSON	`--format "{{ json . }}"`
jsonPretty	Outputs a human-readable JSON with indented by 2 spaces	`--format "table {{ jsonPretty . }}"`
upper	Convert string to uppercase	`--format "{{upper .Name}}\t{{upper .Context}}"`
lower	Convert string to lowercase	`--format "{{lower .Name}}\t{{lower .Context}}"`
title	Convert the first letter to uppercase of a string	`--format "{{title .Name}}\t{{title .Context}}"`

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

Import SSL Certificates for Secure HTTP Communication with API Manager¶

Different environments of API Manager can have different SSL certificates for secure HTTP communications. The default certificate of WSO2 API Manager 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 WSO2 certificate or a CA-signed certificate of a CA (Certificate Authority) trusted by the OS, these certificates will be imported by default to the controller. If the CA or the certificate is new or does not get imported by default, you can add the certificate to the /home/.wso2apictl/certs directory. The certificates added to this directory will be imported whenever an action is performed with the controller. Any DER or PEM encoded certificate with file extensions of *.pem, *.crt or *.cer can be used with the controller.

Info

If you are using windows, CA certs will not be imported by default and has to be added to the /home/.wso2apictl /certs directory.

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/Applications in an environment¶

Delete an API/Application in an environment¶

Change status of an API in an environment¶

Formatting the outputs of list¶

Available formatting options¶

Set token type¶

Set HTTP request timeout¶

Set export directory¶

Import SSL Certificates for Secure HTTP Communication with API Manager¶