Feature Availability
- This feature is only available with the WSO2 WUM updates from July 8, 2019 onwards. For more information on updating WSO2 API Manager, see Updating WSO2 API Manager.
The WSO2 API Manager Command Line Interface(CLI) tool can be used to create APIs without using the API Publisher portal. You can use this feature to create an API specification when you already have a Swagger or Open API specification of your API.
Before you begin...
Running the CLI tool
Step 1 - Deploy the API import/export tool
Download the latest version of WSO2 API Manager from http://wso2.com/products/api-manager/.
- Start WSO2 API Manager.
Download the latest WSO2 API import/export tool (
api-import-export-2.6.0-v17.war
) from here.Note that the import/export tool attached is specific to this version of WSO2 API Manager.
Make sure to delete all previous versions of the web app (e.g.,
api-import-export-2.6.0-v17.war
), both the compressed and the extracted files, before copying over the new web app.- This version of the API Import and Export web application is compatible with the WSO2 WUM updates from July 8, 2019, onwards. For more information on updating WSO2 API Manager, see Updating WSO2 API Manager.
- The previous version of the web application which is compatible with WUM updates that are prior to the above-mentioned date can be download from here.
- Note that API update support in the targeted environment is available only with the
api-import-export-2.6.0-v14.war
version onwards.
Copy the downloaded
api-import-export-2.6.0-v17.war
file to the<API-M_HOME>/repository/deployment/server/webapps
folder.
The file is automatically deployed as hot deployment is enabled.
Step 2 - Optionally, set the proxy environment variables for CLI
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 CLI via a proxy server. After one of the following environment variables is set in your environment where CLI is used, all the requests will go through the proxy server specified.
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>"
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:[email protected]:3128" export HTTPS_PROXY="https://testuser:[email protected]:3128" export http_proxy="http://testuser:[email protected]:3128" export https_proxy="https://testuser:[email protected]:3128"
In conjunction with the above proxy configurations, calls from the CLI to particular hosts that need to bypass proxies can be configured via either the NO_PROXY
or no_proxy
environment variables.
export NO_PROXY="https://<host-name>:<port>" export no_proxy="https://<host-name>:<port>"
export NO_PROXY="https://localhost:3128" export no_proxy="https://localhost:3128"
Step 3 - Run the CLI tool
Download API Controller based on your preferred platform (i.e., Mac, Windows, Linux).
- Extract the downloaded archive containing the CLI Tool to a preferred location and navigate to it from the terminal (using
cd
). - Navigate to the working directory where the executable CLI Tool resides.
Execute the following command to start the CLI tool.
./apimcli
Add the location of the extracted folder to your system's
$PATH
variable to be able to access the executable from anywhere.For further instructions execute the following command.
apimcli --help
Global flags for CLI tool
The following are some global flags that you can use with the CLI tool.
--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
Adding an environment
You can add environments by either manually editing the $HOME/.wso2apimcli/main_config.yaml
file or by running the following CLI command.
apimcli add-env
The directory structure for the configuration files ( $HOME/.wso2apimcli
) will be created upon execution of the apimcli
command.
- Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to add an environment.
apimcli add-env -n <environment-name> \ --registration <registration-endpoint> \ --apim <API-Manager-endpoint> \ --token <token-endpoint> \ --import-export <endpoint-for-environment> \ --admin <admin-REST-API-endpoint> \ --api_list <API-listing-REST-API-endpoint> \ --app_list <application-listing-REST-API-endpoint>
apimcli add-env -n <environment-name> --registration <registration-endpoint> --apim <API-Manager-endpoint> --token <token-endpoint> --import-export <endpoint-for-environment> --admin <admin-REST-API-endpoint> --api_list <API-listing-REST-API-endpoint> --app_list <application-listing-REST-API-endpoint>
Flags:
- Required flags:
--name, -n
There are no short flags for the following flags.--registration
--apim
--token
--import-export
--admin
--api_list
--app_list
Example 1apimcli add-env -n production \ --registration https://localhost:9443/client-registration/v0.14/register \ --apim https://localhost:9443 \ --token https://localhost:8243/token \ --import-export https://localhost:9443/api-import-export-2.6.0-{version}
Example 2apimcli add-env -n dev \ --registration https://localhost:9444/client-registration/v0.14/register \ --apim https://localhost:9444 \ --token https://localhost:8244/token \ --import-export https://localhost:9443/api-import-export-2.6.0-{version} \ --admin https://localhost:9444/api/am/admin/v0.14 \ --api_list https://localhost:9444/api/am/publisher/v0.14/apis \ --app_list https://localhost:9444/api/am/admin/v0.14/applications
Example 1apimcli add-env -n production --registration https://localhost:9443/client-registration/v0.14/register --apim https://localhost:9443 --token https://localhost:8243/token --import-export https://localhost:9443/api-import-export-2.6.0-{version}
Example 2./apimcli add-env -n dev --registration https://localhost:9444/client-registration/v0.14/register --apim https://localhost:9444 --token https://localhost:8244/token --import-export https://localhost:9444/api-import-export-2.6.0-{version} --admin https://localhost:9444/api/am/admin/v0.14 --api_list https://localhost:9444/api/am/publisher/v0.14/apis --app_list https://localhost:9444/api/am/admin/v0.14/applications
Successfully added environment '<environment-name>'
Successfully added environment 'production'
- Required flags:
Logging into API Manager via the CLI tool
Before exporting an API, you need to log in to API Manager to be able to gain the required privileges for the action. Make sure that you have credentials with the proper scopes before logging in via the CLI tool.
The sample command to log in is given below.
apimcli login <Environment> -u <Username> -p <Password>
apimcli login dev -u USER -p PASSWORD123
To log out from the specific environment, use the command given below.
apimcli logout <Environment>
apimcli logout DEV
Create a new API project
- Open a terminal window and navigate to the path you need to create the project.
Execute the command given below to initialize a new API project.
apimcli init <Project Path>
apimcli init SampleAPI
Initializing a new WSO2 API Manager project in /home/user/work/SampleAPI Project initialized Open README file to learn more
A project folder with the following structure will be created in the given directory.
├── api_params.yaml ├── Docs │ └── FileContents ├── Image ├── Meta-information │ ├── api.yaml │ └── swagger.yaml ├── README.md └── Sequences ├── fault-sequence ├── in-sequence └── out-sequence
File/folder Description api.yaml
The specification of the created API. swagger.yaml
The swagger file generated when the API is created. api_params.yaml
Contains environment-specific details.
Adding environment-specific parameters for APIs using api_params.yaml
Refer Adding environment-specific parameters for APIs for more information on configuring api_params.yaml file.
To set a CI/CD pipeline you need to edit the configurations in this file. For instructions on how to use it, see Migrating the APIs to a Different Environment.
Sequences
├── fault-sequence
├── in-sequence
└── out-sequenceTo add custom sequences, save them in xml format and add them to the corresponding folder. E.g., To add a custom in-sequence, save the custom sequence as SampleSequence.xml
and add it to theSequences/in-sequence/
directory.Open the
api.yaml
file. You can edit the mandatory configurations listed below.Field Description apiName
The name of API without spaces. context
Context of the API in API Manager with a leading slash. productionUrl
Production endpoint for API. sandboxUrl
Sandbox endpoint for API. For more information about the configurations, go to the gist.
api.yamlid: providerName: admin apiName: "" version: 1.0.0 type: HTTP context: "" availableTiers: - name: Unlimited status: CREATED visibility: public transports: http,https productionUrl: http://localhost:8080 sandboxUrl: http://localhost:8081
After editing the mandatory fields, you can import the API using the following command.
apimcli import-api --file ./SampleAPI --environment dev
For more information, see Migrating the APIs to a Different Environment.
To publish the API immediately after importing, set the
status
field to "PUBLISHED"
Generate API projects using a Swagger/Open API specification
You can user Swagger2 and OpenAPI3 specifications to generate an API. File format should be yaml or json. A sample command is given below.
apimcli init --oas <Path to API specification> SampleAPI
apimcli init --oas /home/user/sampleAPI.json SampleAPI
To import the created API to your preferred environment, use the command given below.
apimcli import-api -f <Path to API> -e <Environment>
apimcli import-api --file ./SampleAPI --environment dev
You can also initialize an API project from a remote Swagger/Open API specification. The sample command is given below.
apimcli init --oas https://petstore.swagger.io/v2/swagger.json PetstoreAPI
Change the default API template
APIs are generated using a default template specified in the HOME/.wso2apimcli/default_api.yaml
file. You can edit this file to change how the API projects are initialized. This file contains the same notation as the api.yaml
file. If user prefers to generate APIs with predefined set of values for tags, descriptions, throttling tiers, etc., it can be defined through the default_api.yaml.
Generate APIs with dynamic data
You can initialize APi projects with dynamic data using an additional definition file. The definition file will have the field names (e.g., apiName, version) as variables. A sample is shown below. Part of a definition file listed below. In here apiName and version are denoted as environment variables(on usual notation). Upon execution, the CLI tool will automatically inject values from the environment to the definition
id: providerName: admin apiName: $APINAME version: $APIVERSION
Execute the following command to create the project.
apimcli init MyAPI --definition <path>/definition.yaml
When executing the command, the CLI tool automatically injects the values to the API definition.
To make this work you will need to set up required environment variables according to your OS. In a Linux/Unix environment, it can be done using
export APINAME=MyAPI export APIVERSION=1.0.0
API File reference
Please find it in https://github.com/wso2/product-apim-tooling/blob/master/import-export-cli/box/resources/init/sample_api.yaml
Demonstration
Quick demonstration video can be found as follow.