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
- 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
- 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
Download and Initialize the CTL Tool¶
- Navigate to the API Management Tooling page - https://wso2.com/api-management/tooling/
- Click Download button under Dev-Ops Tooling according to 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.
-
Execute the following command to start the CTL Tool.
The directory structure for the configuration files (./apictl
$HOME/.wso2apictl
) will be created upon the execution of theapictl
command. -
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
- 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. -
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¶
- Make sure that WSO2 API Manager is started and the CTL tool is running.
For more information, visit 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, visit 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, visit 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 prompt to provide both username and password.
If you runapictl 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
- 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, visit 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
-
List APIs of an Environment¶
By following the below steps, you can 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, visit Download and Initialize the CTL Tool. - Log in to the API Manager in the environment by following steps 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¶
You can 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, visit Download and Initialize the CTL Tool. - Log in to the API Manager in the environment by following steps 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¶
For testing purposes, the CTL tool allows generating a JWT/OAuth token to invoke an API by subscribing from a default application.
- Make sure that WSO2 API Manager is started and the CTL tool is running.
For more information, visit Download and Initialize the CTL Tool. - Log in to the API Manager in the environment by following steps 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 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
- 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 :