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.
The directory structure for the configuration files (apictl
<USER_HOME>/.wso2apictl
) will be created upon the execution of theapictl
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 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
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:9443/client-registration/v0.15/register \ --apim https://localhost:9443 \ --token https://localhost:8243/token \
apictl add-env -e dev --registration https://localhost:9443/client-registration/v0.15/register --apim https://localhost:9443 --token https://localhost:8243/token
Example
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
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
Successfully added environment '<environment-name>'
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
- Required :
-
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¶
- 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
- Optional :
-
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.
- 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 runapictl 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
- Optional :
-
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¶
-
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
- Required :
-
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
- Required :
-
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.yaml
file. 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
- Required :
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)
- Required :
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
- Required :