Initializing projects using the CLI Tool

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
Step 2 - Optionally, set the proxy environment variables for CLI
Step 3 - Run 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 1

apimcli 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: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 1

apimcli 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'

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-sequence	To 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 the `Sequences/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.yaml
```
id:
  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.
- Command
- Sample
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

sample-additional-definition.yaml

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.

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.