Managing Choreo Connect¶

WSO2 API Controller (apictl) can be used as a developer CLI tool for Choreo Connect. It enables interacting with one or more Choreo Connect environments without having to perform the following tasks via the WSO2 API Manager (WSO2 API-M).

Deploy an API
View the list of deployed APIs
Undeploy an API

Info

Before you begin

Download the Choreo Connect distribution from the github release page's and follow the Quick Start Guide attached with the release.
Make sure the apictl is downloaded and initialized, if not follow the steps in Download and Initialize the apictl. Following the guide upto Check the version of the apictl will be sufficient to continue.
Remember to add the cert of Choreo Connect into /home/<your-pc-username>/.wso2apictl/certs to communicate via https (to avoid having to use insecure mode with -k or --insecure). Click here for more information.

Add a Choreo Connect Environment¶

A Choreo Connect here refers to the entire cluster which includes all three components: adapter, router and enforcer. By adding a Choreo Connect environment, the URL to the adapter will be stored in a configuration file, and therefore enables login.

Once you have added a Choreo Connect environment, and logged in, other commands such as apictl mg deploy api can be used by only specifying an environment. This allows you to use such commands without entering the Choreo Connect adapter URL, username, and password every time.

Command

apictl mg add env <environment-name> --adapter <adapter-url>

Info

Flags:

Mandatory :
--adapter or -a : The Choreo Connect adapter host url with port

Example

apictl mg add env prod --adapter  https://localhost:9443

Log in to a Choreo Connect Environment¶

Log in will get an access token from the Choreo Connect adapter and store it for further commands.

Command
```
apictl mg login <environment-name>
```
```
apictl mg login <environment-name> -u <username>
```
```
apictl mg login <environment-name> -u <username> -p <password>
```
Tip

If you run apictl mg login <environment-name> you are prompted to provide both the username and the password. If you run apictl mg login <environment-name> --username <username>, you are prompted to provide the password. If you include the flag --password-stdin, you can provide the password in a file as well. For an example,
```
cat <file-with-the-password> | apictl mg login <environment-name> -u <username> --password-stdin
```
Info

Flags:
- Optional :
  --username or -u : Username for login
  --password or -p : Password for login
  --password-stdin : Get password from stdin
Example
```
apictl mg login dev
```
```
apictl mg login dev -u admin
```
```
apictl mg login dev -u admin -p admin
```
```
cat ~/.mypassword | apictl mg login dev -u admin --password-stdin
```
- Response
  Response FormatExample Response
  Successfully logged into Choreo Connect Adapter in environment: <environment-name>
  Successfully logged into Choreo Connect Adapter in environment: dev
Warning

Using --password in CTL is not secure. Instead, you can use --password-stdin to include password file or provide the password when prompted.

Deploy an API¶

In order to deploy, let us first create an API project. Follow the steps in Initialize an API Project to create an API project using apictl.

An API project can be deployed to a Choreo Connect using the following commands.

Command
```
apictl mg deploy api -e <environment-name> -f <api-project-file-path>
```
```
apictl mg deploy api ---environment <environment-name> --file <api-project-file-path>
```
Tip

In an API project, the API name and the API version given in the api.yaml will be taken as the name and version of the API once deployed.
Tip

When trying to deploy, if an API with the same name, version, virtual host combination already exists in the Choreo Connect adapter, an error response will be given saying that the API already exists.

In order to override the existing API or deploy an API without considering whether it already exists or not, include the flag --override or its shorthand -o to the same command above. For an example,
```
apictl mg deploy api -e dev -f petstore -o
```
Info

Flags:
- Mandatory :
  -e, --environment : Choreo Connect adapter environment to add the API
  -f, --file : Filepath of the apictl project to be deployed
- Optional :
  -o, --override : Whether to deploy an API irrespective of its existence. Overrides when exists.
  --skip-cleanup : Whether to keep all temporary files created during the deploy process
Example
```
apictl mg deploy api -e dev -f petstore
```
```
apictl mg deploy api --environment dev --file petstore
```
```
apictl mg deploy api -e dev -f petstore --override
```
```
apictl mg deploy api -e dev -f petstore -o --skip-cleanup
```

Response

DeployedAPI Already ExistsDeployed or Updated

Successfully deployed API to Choreo Connect.

Unable to deploy API. API already exists. Status: Conflict 409

Successfully deployed/updated the API in Choreo Connect.

List Deployed APIs¶

This command can be used to list the deployed APIs on a given Choreo Connect adapter environment.

Command
```
apictl mg get apis -e <environment-name>
```
Tip

By default, the number of APIs listed will be limited to 25. To increase or decrease the limit set the flag --limit or its shorthand flag -l. For an example,
```
apictl mg get apis -e dev --limit 100
```
Tip

Currently, these APIs can be filtered by API type. The supported types are http and ws (web socket). Use the flag --query or its shorthand flag -q to filter APIs.
```
apictl mg get apis -e dev --query type:http
```
Info

Flags:
- Mandatory :
  -e, --environment : Choreo Connect adapter environment to list the APIs from
- Optional :
  -l, --limit : Maximum number of APIs to return
  -q, --query : Query to filter the APIs
Example
```
apictl mg get apis -e dev
```
```
apictl mg get apis -q type:http --environment dev --limit 100
```
```
apictl mg get apis -q type:ws -e dev -l 10
```

Response

Limit flag not set. Set to default: 25
APIs total: 2 received: 2
NAME                VERSION             TYPE                CONTEXT         GATEWAY_ENVS
SwaggerPetstore     1.0.5               HTTP                /v2             [Production and Sandbox]
SwaggerPetstore1    1.0.5               WS                  /v2             [Production and Sandbox]

Undeploy an API¶

This command can be used to remove an API from the Choreo Connect.

Command

apictl mg undeploy api -e <environment-name> -n <api-name> -v <api-version>

apictl mg undeploy api -e <environment-name> -n <api-name> -v <api-version> --vhost <vhost>

Info

Flags:

Mandatory :
-e, --environment : Choreo Connect adapter environment to undeploy the API from
-n, --name : API name
-v, --version : API version
Optional :
-t, --vhost : Virtual host the API belongs to

Example

apictl mg undeploy api -e dev -n petstore -v 0.0.1

apictl mg undeploy api --name SwaggerPetstore --version 0.0.1 -e dev

apictl mg undeploy api -n petstore -v 0.0.1 -e dev --vhost www.pets.com

Response

API undeployed from Choreo Connect successfully!

Log out from a Choreo Connect Environment¶

This command can be used to logout from a Choreo Connect adapter environment. Once this command is executed, the access token of the Choreo Connect adapter will be erased from apictl.

Command

apictl mg logout <environment-name>

Example

apictl mg logout dev

Response

Response FormatExample Response

Logged out from Choreo Connect Adapter in environment: <environment-name>

Logged out from Choreo Connect Adapter in environment: dev

Remove a Choreo Connect Environment¶

This command can be used to remove a Choreo Connect environment from apictl. Once this command is executed, it will delete the adapter URL and its access token first, and then remove the Choreo Connect environment from apictl.

Command

apictl remove env <environment-name>

Example

apictl remove env dev

Response

Response FormatExample Response

Successfully removed environment '<environment-name>'

Successfully removed environment 'dev'