@apistudio/apim-cli NPM

CLI Support in API Studio

APIM CLI provides the Command Line Interface (CLI) support for webMethods API Management. In webMethods API Studio you can build, deploy, and test the deployed assets by using APIM CLI. These following sections describe operations that you can do such as build, deploy, and test by using the CLI with some examples.

Installing APIM CLI

Make sure that you have Node.js, whose version is higher than 20.15.0 and less than 21.0.0, installed before you install APIM CLI.

Run the following command in the command line to install APIM CLI.

npm install -g @apistudio/apim-cli

wm apim build

This operation builds and archives the specified project assets. APIs can have external dependencies referenced, hence when you build a project it includes all these references provided in the local folder.

Syntax

wm apim build [options][projects]

Specifies the projects in the local folder you want to build. You can provide multiple projects by providing comma separated project names as input.

The following table lists all available options for the wm apim build command and their descriptions.

Options Description

Command	Description
`-l, --localDir`	Path of the local folder of the specified studio projects. This argument is mandatory.
`-a, --all`	Use `--all` to include all projects in the given local directory. If you do not want to build all projects in the given local directory, then specify the project name that is required.
`-n, --names`	Specify the API kind in the format `namespace:apiname:version`. You can provide multiple asset names as comma-separated entries. Studio supports only API assets.
`-o, --output build_output_path`	Provide the name and path where the output zip file should be stored. If you do not specify the path, the built project is stored in the directory from where you run the command.
`-d, --debug`	Enables the debug mode.
`-h, --help`	Displays help for the build command.

1. Building a single project

Syntax

wm apim build Projectname --localDir local_dir_path --output build_output_path

Example

wm apim build Project1 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip

Builds a project project_build.zip from a single project file, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.

Outcome

As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

2. Building multiple projects

Syntax

wm apim build Project1 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip

wm apim build Projectname1,Projectname2  --localDir local_dir_path --output build_output_path

Example

wm apim build Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip

Builds a project project_build.zip from two project files, Project1 and Project2, located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.

Outcome

As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

3. Building all projects in the local directory

Syntax

wm apim build --all --localDir local_dir_path --output build_output_path

Example

wm apim build --all --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip

Builds a project project_build.zip by bundling all the projects located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.

Outcome

As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

4. Building an API

Syntax

wm apim build Projectname1 --names namespace:name:version  --localDir local_dir_path --output build_output_path

Example

wm apim build Project1 --names dev:TestPayments:1.0 --localDir /Users/user1/Desktop/apistudio_localdir --output ./builds/project_build.zip

Builds an API project_build.zip from a single API file specified by its name dev:TestPayments:1.0 located in the local directory /Users/user1/Desktop/apistudio_localdir and places it in the /builds folder.

Outcome

As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

5. Building a project without --output

Syntax

wm apim build Projectname --localDir local_dir_path

Example

wm apim build Project1 --localDir /Users/user1/Desktop/apistudio_localdir

Builds a project project_build.zip from the project file, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir. When you do not provide the --output option, APIM CLI builds it with a fixed standard package name, for example, studio-projectname-build.zip and archives it in the same location from where the command is run.

Outcome

As the build progresses, it lists the assets added. On successful completion you will see the message Build completed successfully!. In addition it displays the locaton where the build is placed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

Deploy

This operation deploys the build to webMethods API Gateway.

Syntax

wm apim deploy [options][projects]

projects. Specifies the projects in the local folder you want to deploy. You can provide multiple projects by providing comma separated project names as input.

The following table lists all available options for the wm apim deploy command and their descriptions.

Options Description | Commands | Description | |-----------------------------|--------------| | -l, --localDir | Path of the local folder of the specified studio projects. This is a mandatory argument. | | -a, --all | Use --all to include all projects in the given local directory. If you do not want to build all projects in the given local directory, then specify the project name that is required. | | -n, --names | Specify the API kind in the format namespace:apiname:version. You can provide multiple asset names as comma-separated entries as input. Studio supports only API assets. | | -a, --archive archive | Specify the archive to be deployed. | | -t, --target target | Specify the endpoint of the API Gateway instance to which the asset has to be deployed. This is a mandatory argument. | | -u, --username username | Provide the username of the API Gateway instance to which the asset is deployed. This user must have Manage APIs functional privilege. This is a mandatory argument. | | -pwd, --password password | Provide the password of the API Gateway instance to which the asset is deployed. If you do not provide the password, CLI prompts for the password, where you can provide the masked password. | | -ow, --overwrite | Specify if you want to overwrite the existing assets on the API Gateway instance where the specified asset is being deployed. | | -d, --debug | Enables the debug mode. | | -h, --help | Displays help for the build command. |

1. Deploying a single project

Syntax

wm apim deploy Projectname --localDir local_dir_path  --target "http://host:port"  
--username username --password password --overwrite

Example

wm apim deploy Project1 --localDir /Users/user1/Desktop/apistudio_localdir --target "http://host:port" --username "******" --password "******" --overwrite

Deploys a single project file, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.

Outcome

As the deployment progresses, it lists the asset being added followed by deployment status of the asset. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoints of the APIs in the project is displayed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

2. Deploying multiple projects

Syntax

wm apim deploy Projectname1,Projectname2  
--localDir local_dir_path 
--target "http://host:port" 
--username username --password password --overwrite

Example

wm apim deploy Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir 
--target "http://host:port" 
--username "******" --password "******" --overwrite

Deploys two projects from two project files, Project1 and Project2, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.

Outcome

As the deployment progresses, it lists the assets being added followed by deployment status of the assets. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoints of the APIs in the projects is displayed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

3. Deploying all projects

Syntax

wm apim deploy --all --localDir local_dir_path 
--target "http://host:port" 
--username username --password password --overwrite

Example

wm apim deploy --all --localDir /Users/user1/Desktop/apistudio_localdir 
--target "http://host:port" 
--username "******" --password "******" --overwrite

Deploys all projects located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.

Outcome

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

4. Deploying an API

Syntax

wm apim deploy Projectname1 --names namespace:name:version 
--localDir local_dir_path --target "http://host:port" 
--username username --password password --overwrite

Example

wm apim deploy Project1 --names dev:TestPayments:1.0 
--localDir '/Users/user1/Desktop/apistudio_localdir'  --target 'http://host:port' 
--username "******" --password "******" --overwrite

Deploys an API specified by its name dev:TestPayments:1.0, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.

Outcome

As the deployment progresses, it lists the asset being added followed by deployment status of the assets. On successful deployment you will see the deployment success message Deployment to api gateway is successful!. In addition the gateway endpoint of the API is displayed.

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

5. Deploying an archive

Syntax

wm apim deploy --archive --localDir local_dir_path 
--target "http://host:port" 
--username username --password password --overwrite

Example

wm apim deploy --archive /Users/user1/Desktop/apistudio_localdir/build.zip 
--target "http://host:port" --username "******" --password "****" 
--overwrite

Deploys an archive, build.zip, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. If there is any identical asset in the API Gateway instance then the overwrite argument helps in overwriting that asset.

Outcome

In case of any errors, a deployment failure messgae with the reason for failure is displayed so you can take the corrective action.

Test

This operation tests the projects deployed to API Gateway.

Syntax

wm apim test [options][projects]

projects. Specifies the projects in the local folder that have to be tested. You can provide multiple projects by providing comma separated project names as input.

The following table lists all available arguments for the wm apim test command and their descriptions.

Argument Description | Command | Description | |--------------------------------|--------------| | -l, --localDir localDirpath | Path of the local folder of the specified studio projects. This is a mandatory argument. | | -a, --all | Use --all to include all projects in the given local directory. If you do not want to build all projects in the given local directory, then specify the project name that is required. | | -t, --target target | Specify the endpoint of the API Gateway instance to which the asset has to be deployed. | | -n, --names | Specify the API kind in the format namespace:apiname:version. You can provide multiple asset names as comma-separated entries as input. Studio supports only API assets. | | -u, --username username | Provide the username of the API Gateway instance to which the asset is deployed. This user must have Manage APIs functional privilege. This is a mandatory argument. | | -pwd, --password password | Provide the password of the API Gateway instance to which the asset is deployed. If you do not provide the password, CLI prompts for the password, where you can provide the masked password. | | -de, --deploy | Deploys the projects or the specified asset to webMethods API Gateway during testing. | | -e, --env key=value | Adds or overwrites the environment configuration values in the environment asset file. For example, key1=value1,key2=value2. | | -en, --endpoints | Tests the specified API, as defined by the --names parameter, against the --endpoint value where it is already deployed. | | -d, --debug | Enables the debug mode. | | -h, --help | Displays help for the build command. |

1. Testing a single project

Syntax

wm apim test Projectname --localDir local_dir_path

Example

wm apim test Project1 --localDir /Users/user1/Desktop/apistudio_localdir

Tests the project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

As the tests start, it displays the asset added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.

2. Testing multiple projects

Syntax

wm apim test Projectname1,Projectname2  --localDir local_dir_path

Example

wm apim test Project1,Project2 --localDir /Users/user1/Desktop/apistudio_localdir

Tests the projects, Project1 and Project2, located in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

As the tests start, it displays the assets added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.

3. Testing all projects

Syntax

wm apim test --all --localDir local_dir_path

Example

wm apim test --all --localDir /Users/user1/Desktop/apistudio_localdir

Tests all the projects located in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

4. Testing an API

Syntax

wm apim test Projectname --names namespace:name:version --localDir local_dir_path

Example

wm apim test Project1 --names dev:TestPayments:1.0 --localDir /Users/user1/Desktop/apistudio_localdir

Tests an API specified by its name dev:TestPayments:1.0, located in the local directory /Users/user1/Desktop/apistudio_localdir.

Outcome

As the tests start, it displays the asset added and a list of gateway endpoint of the API. On successful execution of all tests you will see you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the Test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.

5. Testing a project by overwriting the environment configuration

Syntax

wm apim test Projectname --localDir local_dir_path --env key=value

Example

wm apim test Project1 --localDir  /Users/user1/Desktop/apistudio_localdir --env Content-Type=application/json,petId=1

Tests a project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir using the environment configuration values provided in the environment asset file.

Outcome

As the tests start, it displays the asset added and a list of gateway endpoints of the APIs in the project. On successful execution of all tests you will see the message Test executed successully.... In addition, it displays the number of tests passed, number of tests failed and the test status. You would also see the details of each test such as resource, assertion, status and in case of a failed test an appropriate message with the reason for failure.

6. Testing a project using endpoints

Syntax

wm apim test Projectname --names namespace:name:version --localDir local_dir_path --endpoints endpoint

Example

wm apim test Project1 --names dev:TestPayments:1.0 --localDir /Users/user1/Desktop/apistudio_localdir 
--endpoints http://host:port/gateway/ProductAPI10/1.0

Tests a project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir using the API endpoint http://host:port/gateway/ProductAPI10/1.0.

Outcome

As the tests start, the display shows the added assets. When all tests run successfully, the message Test executed successully... appears. Additionally, it shows the number of tests passed, the number failed, and the overall test status. You can view details for each test, including the resource, assertion, status, and, for any failed test, an error message explaining the reason for failure.

7. Deploying and testing a project

Syntax

wm apim test Projectname --localDir local_dir_path --target "http://host:port" --username username --password password --deploy

Example

wm apim test Project1 --localDir  C:/Users/user1/Desktop/apistudio_localdir  --target "http://host:port" 
--username "******" --password "******" --deploy

Deploys the project, Project1, located in the local directory /Users/user1/Desktop/apistudio_localdir to the specified API Gateway instance. On successful deployment it tests the deployed project.

Outcome

wm apim help

Displays help for the specified command.

Syntax

wm apim help command_name

Example: Viewing help for the deploy command.

wm apim help deploy

Outcome. This lists the help for the deploy command as follows:

Usage: wm apim deploy options

deploy the projects or the specified archive to API Gateway

Options: | Command | Description | |--------------------------------|--------------| | -l, --localDir <localDir> | Path of the local directory of the specified project asset. For example, C:\local_dir. | | -a, --all | Deploys all projects existing in the local directory. | | -n, --names <names> | Deploys the specified API asset kind. For example, dev:paymentAPI:1.0. | | -ar, --archive <archive> | Deploys the specified archive. For example, C:\dir\build.zip. | | -t, --target <target> | Endpoint of the API Gateway instance to which the asset has to be deployed. | | -u, --username <username> | Username of the API Gateway instance to which the asset has to be deployed. | | -pwd, --password <password> | Password of the API Gateway instance to which the asset has to be deployed. | | -ow, --overwrite | Overwrites the existing assets on the API Gateway instance where the specified asset is being deployed. | | -d, --debug | Enables debug mode. | | -h, --help | Displays help for the command. |

5 months ago

6 months ago

6 months ago

7 months ago

7 months ago

7 months ago

7 months ago

7 months ago