Getting Started with WSO2 API Controller (apictl)¶
WSO2 API Controller (apictl) is a command-line tool providing the capability to move APIs, API Products, and Applications across environments and to perform CI/CD operations. It can also be used to perform these same tasks on a Kubernetes deployment. Furthermore, it can perform WSO2 Micro Integrator (WSO2 MI) server specific operations such as monitoring Synapse artifacts and performing MI management/administrative tasks from the command line.
Download and initialize the apictl¶
-
Download apictl based on your preferred platform (i.e., Mac, Windows, Linux).
-
Extract the downloaded archive of the apictl to the desired location.
- Navigate to the working directory where the executable apictl 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 apictl.
Warn
If you have previously used an apictl old version, backup and remove
/home/<user>/.wso2apictl
directory and reconfigure the environments using the 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 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 apictl¶
The following are some global flags that you can use with any apictl 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 apictl¶
Run the following apictl command to check the version.
- Command
apictl version
-
Response
Version: 4.0.4 Build Date: 2023-09-05 17:51:10 UTC
Note
Set mode of apictl
From the apictl 4.0.0 onwards the flag (--mode) which was used to set the mode of apictl has been deprecated. Now, you do not need to set the mode of apictl, because if you want to execute Kubernetes based commads, you just need to add the k8s
keyword after apictl
keyword. (Example: apictl k8s add api
). By default apictl will execute the commands in the default
mode (which means if you did not use k8s
keyword).
You can still use the mode
flag as explained below if you need it, but it will be removed in the future.
-
Command
apictl set --mode <mode>
Example
apictl set --mode default
apictl set --mode kubernetes
The allowed modes are
default
andkubernetes
.
Set proxy environment variables for apictl¶
You can set proxy related HTTP_PROXY
, HTTPS_PROXY
, http_proxy
, and https_proxy
standard environment variables, with or without basic authentication as shown below to send the requests initiated from CTL via a proxy server. After one of the following environment variables is set in your environment where CTL is used, all the requests will go through the proxy server specified.
-
Formats
export HTTP_PROXY="http://<host-name>:<port>" export HTTPS_PROXY="https://<host-name>:<port>" export http_proxy="http://<host-name>:<port>" export https_proxy="https://<host-name>:<port>"
export HTTP_PROXY="http://<username>:<password>@<host-name>:<port>" export HTTPS_PROXY="https://<username>:<password>@<host-name>:<port>" export http_proxy="http://<username>:<password>@<host-name>:<port>" export https_proxy="https://<username>:<password>@<host-name>:<port>"
-
Examples
export HTTP_PROXY="http://localhost:3128" export HTTPS_PROXY="https://localhost:3128" export http_proxy="http://localhost:3128" export https_proxy="https://localhost:3128"
export HTTP_PROXY="http://testuser:password@localhost:3128" export HTTPS_PROXY="https://testuser:password@localhost:3128" export http_proxy="http://testuser:password@localhost:3128" export https_proxy="https://testuser:password@localhost:3128"
Add an environment¶
You can add environments by either manually editing the <USER_HOME>/.wso2apictl/main_config.yaml
file or by running the following apictl command.
apictl add env <environment-name>
- Make sure that the WSO2 API Manager (WSO2 API-M) 4.0.0 version is started and that the 4.0.4 version of apictl is set up.
For more information, see Download and Initialize the apictl. -
Run the following apictl command to add an environment.
-
Command
apictl add env <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> \ --mi <mi-management-endpoint>
apictl add env <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> --mi <mi-management-endpoint>
Info
Flags:
To add a WSO2 API-M
-
Required :
(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 Portal endpoint for the environment
--devportal
: Developer Portal endpoint for the environment -
Optional :
--token
: Token endpoint for the environment
To add a WSO2 MI
- Required :
--mi
: Management endpoint of the Micro Integrator
Tip
When adding an environment, when the optional flags are not given, apictl will automatically derive those from
--apim
flag value.Tip
When token hashing is enabled, The Client Secret value is displayed in plain text only once in
keys.json
file. Therefore, be sure to copy and save it for later use.Note
You can either provide only the flag
--apim
, or all the other 4 flags (--registration
,--publisher
,--devportal
,--admin
) without providing--apim
flag. If you are omitting any of--registration
,--publisher
,--devportal
,--admin
flags, you need to specify--apim
flag with the WSO2 API-M endpoint. In both of the above cases--token
flag is optional and can be used to provide a user-preferred token endpoint. You can use the--mi
flag to add a Micro Integrator instance to an environment. -
-
Adding a WSO2 API-M to an environment using
--apim
flagExample
apictl add env dev \ --apim https://localhost:9443
apictl add env dev --apim https://localhost:9443
-
Adding a WSO2 API-M to an environment using
--registration
,--publisher
,--devportal
,--admin
flagsExample
apictl add env production \ --registration https://idp.com:9444 \ --admin https://apim.com:9444 \ --publisher https://apim.com:9444 \ --devportal https://apps.com:9444 \ --token https://apim.com:9444/oauth2/token
apictl add env production --registration https://idp.com:9444 --admin https://apim.com:9444 --publisher https://apim.com:9444 --devportal https://apps.com:9444 --token https://apim.com:9444/oauth2/token
-
Adding a WSO2 API-M to an environment using some of the
--registration
,--publisher
,--devportal
,--admin
flags along with--apim
flagExample
apictl add env production \ --registration https://idp.com:9444 \ --apim https://apim.com:9444 \ --token https://apim.com:9444/oauth2/token
apictl add env production --registration https://idp.com:9444 --apim https://apim.com:9444 --token https://apim.com:9444/oauth2/token
-
Adding a WSO2 MI to an environment using
--mi
flagExample
apictl add env dev \ --mi https://localhost:9164
apictl add env dev --mi https://localhost:9164
-
Adding both WSO2 API-M and WSO2 MI to an environment
Example
apictl add env test \ --apim https://localhost:9443 \ --mi https://localhost:9164
apictl add env test --apim https://localhost:9443 --mi https://localhost:9164
Note
apictl add-env
command has been deprecated from apictl 4.0.0 onwards. Instead, useapictl add env
as shown above. -
Response
Successfully added environment '<environment-name>'
Successfully added environment 'production'
-
Remove an environment¶
- Make sure that the WSO2 API-M 4.0.0 version is started and that the 4.0.4 version of apictl is set up.
For more information, see Download and Initialize the apictl. -
Run the following apictl command to remove an environment.
-
Command
apictl remove env <environment-name>
Example
apictl remove env 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
-
Get environments¶
- Make sure that the WSO2 API-M 4.0.0 version is started and that the 4.0.4 version of apictl is set up.
For more information, see Download and Initialize the apictl. -
Run the following apictl command to list the environments.
-
Command
apictl get envs
Info
Flags:
- Optional :
--format
: pretty-print environments using templates
- Optional :
-
Response
NAME API MANAGER ENDPOINT REGISTRATION ENDPOINT TOKEN ENDPOINT PUBLISHER ENDPOINT DEVPORTAL ENDPOINT ADMIN ENDPOINT MI MANAGEMENT ENDPOINT <environment-name> <APIM-endpoint> <registration-endpoint> <token-endpoint> <Publisher-endpoint> <DevPortal-endpoint> <admmin-endpoint> <mi-management-endpoint>
NAME API MANAGER ENDPOINT REGISTRATION ENDPOINT TOKEN ENDPOINT PUBLISHER ENDPOINT DEVPORTAL ENDPOINT ADMIN ENDPOINT MI MANAGEMENT ENDPOINT dev https://localhost:9443 https://localhost:9443 https://localhost:9443/oauth2/token https://localhost:9443 https://localhost:9443 https://localhost:9443 production https://localhost:9444 https://localhost:9444 https://localhost:9443/oauth2/token https://localhost:9444 https://localhost:9444 https://localhost:9444 https://localhost:9164 dev-mi https://localhost:9164
Note
Output of the
get envs
command can be formatted with Go Templates. For more information on formatting the get commands, see Formatting the outputs of get commands.Note
apictl list envs
command has been deprecated from the apictl 4.0.0 onwards. Instead useapictl get envs
as shown above.
-
Login to an environment¶
After adding an environment, you can log in to the WSO2 API-M instance in that environment using credentials.
- Make sure that the WSO2 API-M 4.0.0 version is started and that the 4.0.4 version of apictl is set up.
For more information, see Download and Initialize the apictl. -
Run any of the following apictl commands to log in to the environment.
-
Command
apictl login <environment-name>
apictl login <environment-name> -u <username>
apictl login <environment-name> -u <username> -p <password>
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
apictl login dev -u admin -p admin
apictl login dev --username admin --password admin
- Optional :
-
Response
Logged into '<environment-name>' environment
Logged into dev environment
Warning
Using -
-password
in apictl is not secure. You can use--password-stdin
instead. For example,cat ~/.mypassword | ./apictl login dev --username admin --password-stdin
-
Logout from an environment¶
-
Make sure that the WSO2 API-M 4.0.0 version is started and that the 4.0.4 version of apictl is set up.
For more information, see Download and Initialize the apictl. -
Run the following command to log out from the current session of the WSO2 API-M environment.
-
Command
apictl logout <environment-name>
Example
apictl logout dev
-
Set HTTP request timeout¶
Run the following apictl 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 TLS renegotiation mode¶
By default, TLS renegotiation is disabled for the apictl. However, the TLS renegotiation mode can be configured by running the following command, which will be applied globally to all subsequent TLS connections established by apictl.
-
Command
apictl set --tls-renegotiation-mode <never|once|freely>
Example
apictl set --tls-renegotiation-mode freely
Info
Flags:
- Required :
--tls-renegotiation-mode
Allowed values for this flag are,
never: Disable TLS renegotiation
once: Allow TLS renegotiation once
freely: Allow unrestricted TLS renegotiation
- Required :
Set export directory¶
Run the following apictl 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, API Products, and Applications should be saved.
Default :/home/.wso2apictl/exported
- Required :
Import SSL certificates for Secure HTTP communication with WSO2 API-M¶
Different environments of WSO2 API-M can have different SSL certificates for secure HTTP communications. The default certificate of WSO2 API-M 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 apictl. If the CA or the certificate is new or does
not get imported by default, you can add the certificate to the certs
directory found in
APICTL_CONFIG_DIR/.wso2apictl
.
(The default location of the certs directory is /home/.wso2apictl/certs
)
The certificates added to this directory will be imported whenever an action is performed with apictl. Any
DER or PEM encoded certificate with the file extensions of *.pem
, *.crt
or *.cer
can be used with apictl.
Info
If you are using Windows, CA certs will not be imported by default and have to be added to the certs
directory.