In this community call, we will discuss the WSO2 API Controller (apictl) 4.0.x - Introduction - New Features and Improvements - Demonstration - Q&A

1. November 24th, 2021
WSO2 API Manager Community Call
Say “Hello” to WSO2 API Controller (apictl) 4.0.x

2. Hello!
Wasura Wattearachchi
Senior Software Engineer
wasura@wso2.com

3. 3
Overview
INTRODUCTION
Heads up before starting
1
NEW FEATURES AND IMPROVEMENTS
Six significant changes
2
DEMONSTRATION
Hands on experience
3

4. 4
Overview
INTRODUCTION
Heads up before starting
1
NEW FEATURES AND IMPROVEMENTS
Six significant changes
2
DEMONSTRATION
Hands on experience
3
● Support Import/Export Revisions of APIs and API Products
● Introducing New Structures and Schemas
● Support for Choreo Connect and WSO2 Micro Integrator (WSO2 MI)
● Introduced New Improved Commands while Deprecating some Old apictl Commands
● Parameters Files Enhancements
● Revolutionized VCS (Version Control System) Support with Source and Deployment Repositories

5. Introduction

6. 6
API Manager Tooling Evolution
2018
April
apimcli 1.0.0
Compatible with
WSO2 API Manager
2.2.0
2018
July
apimcli 1.1.0
Compatible with
WSO2 API
Manager 2.5.0
2019
August
apimcli 2.0.x
Compatible with
WSO2 API Manager
2.6.0
(Latest patch release
apimcli 2.0.15) 2019
October
apictl 3.0.x
Compatible with
WSO2 API Manager
3.0.0
(Latest patch release
apictl 3.0.1)
2020
April
apictl 3.1.x
Compatible with
WSO2 API Manager
3.1.0
(Latest patch release
apictl 3.1.4) 2020
August
apictl 3.2.x
Compatible with
WSO2 API Manager
3.2.0
(Latest patch release
apictl 3.2.4)
2021
April
apictl 4.0.0
Compatible with
WSO2 API Manager
4.0.0
(Latest patch release
apictl 4.0.1)

7. What is WSO2 API Controller (apictl)?
7
● The WSO2 API Manager (WSO2 API-M) family member to
perform CI/CD tasks related to APIs, API Products and
Applications.
⦿ Managing WSO2 API-M environments
⦿ Listing APIs, API Products and Applications
⦿ Creating API projects
⦿ Importing/exporting APIs, API Products and Applications
⦿ Generating tokens for APIs and API Products
⦿ Managing APIs on a Kubernetes (k8s) deployment etc
● apictl 4.0.0 has been released on the 5th May 2021 with
WSO2 API-M 4.0.0.

8. New Features and Improvements

9. 9
1. Support Import/Export Revisions of APIs and API
Products
Previous Community Call on the API Revisions Support
https://www.youtube.com/watch?v=DdfrSca1PhE

10. Export an API Revision
10
Flags:
● Required :
--name or -n : Name of the API to be exported
--version or -v : Version of the API to be exported
--environment or -e : Environment from which the
API should be exported
● Optional :
--rev : Revision Number of the API. If not provided,
working copy of the API will be exported.
--provider or -r : Provider of the API.
--latest : Export the latest revision of the API.
--preserve-status : Preserve API status when
exporting. Otherwise, the API
will be exported in the CREATED
status. The default value is true.
--format : File format of exported archive (JSON or
YAML). The default value is YAML.
apictl export api -n <API-name> -v <version> --rev
<revision-number> -r <provider> -e <environment>
--preserve-status=<preserve-status> --format
<export-format>
Import an API Revision
apictl import api --file <path-to-API-archive>
--environment <environment>
--preserve-provider=<preserve_provider>
--update=<update_api> --skip-cleanup=<skip-cleanup>
--params <environment-params-file> --rotate-revision
Flags:
● Required :
--file or -f : The file path of the API to import.
--environment or -e : Environment to which the API should
be exported.
● Optional :
--rotate-revision : If the maximum revision limit reached,
delete the oldest revision and create a
new revision.
--skip-deployments : Skip the deployment environments
specified in the project and only update
the working copy of the API.
--preserve-provider : Preserve existing provider of API after
importing. Default value is true.
--update : Update an existing API or create a new API in the
importing environment.
--params : Define the API Manager environment params file.
--skip-cleanup : Leave all temporary files created in the
apictl during import process. Default value
is false.

11. Export an API Product Revision
11
Flags:
● Required :
--name or -n : Name of the API Product to be exported
--environment or -e : Environment from which the API
Product should be exported
● Optional :
--rev : Revision Number of the API Product. If not
provided, working copy of the API Product will be
exported.
--provider or -r : Provider of the API Product.
--latest : Export the latest revision of the API Product.
--format : File format of exported archive (JSON or
YAML). The default value is YAML.
apictl export api-product -n <API Product-name>
--rev <revision-number> -r <provider> -e
<environment> --format <export-format>
Import an API Product Revision
apictl import api-product -f
<path-to-API-Product-archive> -e <environment>
--rotate-revision
Flags:
● Required :
--file or -f : The file path of the API Product to import.
--environment or -e : Environment to which the API Product
should be exported.
● Optional :
--preserve-provider : Preserve existing provider of API Product after
importing. Default value is true.
--rotate-revision : If the maximum revision limit reached, delete the
oldest revision and create a new revision.
--skip-deployments : Skip the deployment environments specified in
the project and only update the working copy of
the API Product.
--import-apis : Import dependent APIs to the environment along with
the API Product. Default value is false.
--update-api-product : Update an existing API Product or create a
new API Product in the importing environment. Default
value is false.
--update-apis : Update dependent APIs of the API Product. Default
value is false.
--params : Define the API Manager environment params file.
--skip-cleanup : Leave all temporary files created in the apictl during
import process. Default value is false.

12. Get (list) API Revisions
12
Flags:
● Required :
--name or -n : Name of the API to get the revisions
--version or -v : Version of the API to get the revisions
--environment or -e : Environment to be searched
● Optional :
--provider or -r : Provider of the API
--query or -q : Search query pattern
--format : pretty-print environments using templates
apictl get api-revisions --name <API-name> --version
<version> --provider <provider> --environment
<environment> --query <deployment-search-query>
Get (list) API Product Revisions
apictl get api-product-revisions --name
<API-Product-name> --provider <provider> --environment
<environment> --query <deployment-search-query>
Flags:
● Required :
--name or -n : Name of the API Product to get the revisions
--environment or -e : Environment to be searched
● Optional :
--provider or -r : Provider of the API Product --query or -q :
Search query pattern
--format : pretty-print environments using templates

13. 13
2. Introducing New structures and Schemas

14. 14
<APIName>-version
├── api.yaml
├── api_meta.yaml
├── deployment_environments.yaml
├── Client-certificates
│ ├── Alias1.crt
│ ├── Alias2.crt
│ └── client_certificates.yaml
├── Definitions
│ |── swagger.yaml
| |── schema.graphql
| └── graphql-complexity.yaml
├── Docs
│ ├── Doc1
│ │ ├── document-file.pdf
│ │ └── document.yaml
│ ├── Doc2
│ │ ├── Doc2
│ │ └── document.yaml
│ ├── Doc3
│ │ ├── Doc3
│ │ └── document.yaml
│ └── Doc4
│ └── document.yaml
├── Endpoint-certificates
│ ├── Alias3.crt
│ ├── Alias4.crt
│ └── endpoint_certificates.yaml
├── Image
| └── <imageName>.extension
├── WSDL
| └── <APIName>-<version>.wsdl
└── Sequences
├── fault-sequence
| |── Custom
| | |── <custom-sequence-1-name.xml>
| | └── <custom-sequence-2-name.xml>
| └── <sequence-name.xml>
├── in-sequence
| |── Custom
| | └── <custom-sequence-name.xml>
| └── <sequence-name.xml>
└── out-sequence
|── Custom
| └── <custom-sequence-name.xml>
└── <sequence-name.xml>
<APIName>-version
├── api_params.yaml
├── Meta-information
│ ├── api.yaml
│ |── swagger.yaml
| |── endpoint_certificates.yaml
| └── schema.graphql
├── Docs
| |── FileContents
│ |── InlineContents
| └── docs.yaml
├── Image
| └── icon.extension
├── WSDL
| └── <APIName>-<version>.wsdl
└── Sequences
├── fault-sequence
| |── Custom
| | └── <custom-sequence-name.xml>
| └── <sequence-name.xml>
├── in-sequence
| |── Custom
| | └── <custom-sequence-name.xml>
| └── <sequence-name.xml>
└── out-sequence
|── Custom
| └── <custom-sequence-name.xml>
└── <sequence-name.xml>
3.2.0
4.0.0
API Structure

15. 15
<APIProductName>-version
├── api_product.yaml
├── api_product_meta.yaml
├── deployment_environments.yaml
├── Client-certificates
│ ├── Alias1.crt
│ ├── Alias2.crt
│ └── client_certificates.yaml
├── APIs
│ ├── <1stAPIName>_version
│ |── <2ndAPIName>_version
| |──
| └── <NthAPIName>_version
├── Definitions
| └── swagger.yaml
├── Docs
│ ├── Doc1
│ │ ├── document-file.pdf
│ │ └── document.yaml
│ ├── Doc2
│ │ ├── Doc2
│ │ └── document.yaml
│ ├── Doc3
│ │ ├── Doc3
│ │ └── document.yaml
│ └── Doc4
│ └── document.yaml
└── Image
└── <imageName>.extension
<APIProductName>-version
├── APIs
│ ├── <1stAPIName>_version
│ |── <2ndAPIName>_version
| |──
| └── <NthAPIName>_version
├── Meta-information
│ ├── api.yaml
| └── swagger.yaml
├── Docs
| |── FileContents
│ |── InlineContents
| └── docs.yaml
└── Image
└── icon.extension
3.2.0
4.0.0
API Product Structure

16. 16
<Application-owner>_<Application-name>.zip
├── application.yaml
└── application_meta.yaml
<exported-Application>.zip
└── <Application-Name>.json
3.2.0
4.0.0
Application Structure

17. 17
type: api
version: v4.0.0
data:
name : SampleAPI
version: 1.0.0
context: /sampleapi
endpointConfig:
endpoint_type: http
production_endpoints:
url: http://prod.wso2.com
sandbox_endpoints:
url: http://sand.wso2.com
endpointImplementationType: ENDPOINT
lifeCycleStatus: CREATED
policies:
- Unlimited
provider: admin
transport:
- http
- https
type: HTTP
visibility: PUBLIC
id:
providerName: admin
apiName: SampleAPI
version: 1.0.0
type: HTTP
context: /sampleapi
availableTiers:
- name: Unlimited
status: PUBLISHED
visibility: public
transports: http,https
productionUrl: http://localhost:8080
sandboxUrl: http://localhost:8081
3.2.0
4.0.0
API Schema (api.yaml)

18. 18
type: api
version: v4.0.0
data:
name : SampleAPI
version: 1.0.0
context: sampleapi
endpointConfig:
endpoint_type: http
production_endpoints:
url: http://prod.wso2.com
sandbox_endpoints:
url: http://sand.wso2.com
endpointImplementationType: ENDPOINT
lifeCycleStatus: CREATED
policies:
- Unlimited
provider: admin
transport:
- http
- https
type: HTTP
visibility: PUBLIC
id:
providerName: admin
apiName: SampleAPI
version: 1.0.0
type: HTTP
context: sampleapi
availableTiers:
- name: Unlimited
status: PUBLISHED
visibility: public
transports: http,https
productionUrl:
http://localhost:8080
sandboxUrl: http://localhost:8081
3.2.0
4.0.0
API Schema (api.yaml)

19. 19
3. Support for Choreo Connect
and WSO2 Micro Integrator
(WSO2 MI)

20. 20
apictl as a Developer CLI Tool for Choreo Connect (API Microgateway)
● This feature of apictl 4.0.0, enables interacting with one or more Choreo
Connect environments without having to perform the tasks such as deploy
an API, view the list of deployed APIs and un-deploy an API via the WSO2
API-M.
● A new alias named mg has been allocated to the commands related to
Choreo Connect.
● Examples:
apictl mg login <environment-name>
apictl mg get apis -e <environment-name>
apictl mg undeploy api -e <environment-name> -n <api-name> -v <api-version>
Documentation
https://apim.docs.wso2.com/en/4.0.0/install-and-setup/setup/api-controller/managing-choreo-connect/managing-choreo-connect-with-ctl

21. 21
Merged Micro Integrator (MI) CLI Commands with apictl
● With apictl 4.0.0, the monitoring tasks of the Synapse artifacts (deployed
in a specified MI server) can be done along with various management and
administration tasks using the command line.
● A new alias named mi has been allocated to the commands related to MI.
● Examples:
apictl mi login <environment-name>
apictl mi get apis -e <environment>
apictl mi add user [user-name] -e <environment>
Documentation
https://apim.docs.wso2.com/en/4.0.0/install-and-setup/setup/api-controller/managing-integrations/managing-integrations-with-ctl

22. 22
4. Introduced New improved Commands while
Deprecating some Old apictl Commands

23. Deprecated Command New Command
apictl import-api [flags] apictl import api [flags]
apictl import-app [flags] apictl import app [flags]
apictl export-api [flags] apictl export api [flags]
apictl export-apis [flags] apictl export apis [flags]
apictl export-app [flags] apictl export app [flags]
apictl list apis [flags] apictl get apis [flags]
apictl list api-products [flags] apictl get api-products [flags]
apictl list apps [flags] apictl get apps [flags]
apictl list envs [flags] apictl get envs [flags]
apictl get-keys [flags] apictl get keys [flags]
apictl delete api [flags]
apictl delete api [flags]
apictl k8s delete api [flags]
apictl add api [flags] apictl k8s add api [flags]
apictl update api [flags] apictl k8s update api [flags]
apictl add-env [flags] apictl k8s update api [flags]
23
Commands Revamp
apictl [alias] [verb] [noun] [flags]
apictl k8s add api [flags]
apictl <empty> import api [flags]
Alias values
● k8s for Kubernetes related commands
● mg for Choreo Connect related commands
● mi for WSO2 MI related commands
● <empty> for WSO2 API-M related commands
apictl set --mode has been deprecated.

24. 24
5. Parameters Files Enhancements

25. 25
Now
● There is no point in including the
api_params.yaml inside the project.
You will be left with Option 2 only.
● You can not only provide a params
file now, but also you can give a
directory as the params during the
import of an API/API Product.
Then
● Option 1 — Keep inside the API
project so that when importing the
API, the details will be overridden
based on the parameters.
● Option 2 — Use the --params flag to
specify the path to the parameter file
when you are importing the API so
that it will be considered.
Parameters… Then and Now?

26. config:
factor: <suspension_factor>
suspendMaxDuration: <maximum_suspend_time_duration>
suspendDuration: <suspend_time_duration>
suspendErrorCode:
- <suspend_error_code_1>
- <suspend_error_code_2>
- ......................
- <suspend_error_code_n>
retryTimeOut: <no_of_retries_before_suspension>
retryDelay: <retry_delay_in_ms>
retryErroCode:
- <retry_error_code_1>
- <retry_error_code_2>
- ....................
- <retry_error_code_n>
actionSelect: <action_discard_or_fault>
actionDuration: <action_time_duration>
26
Parameters File for an API
environments:
- name: <environment_name>
configs: <multiple_configurations_relevant_to_the_specific_environment>
endpoints:
production:
url: <production_endpoint_url>
config:
factor: <suspension_factor>
---------------------------
sandbox:
url: <sandbox_endpoint_url>
config:
factor: <suspension_factor>
---------------------------
security:
production:
enabled: <whether_security_is_enabled_for_production_endpoint>
type: <endpoint_authentication_type_basic_or_digest_for_production_endpoint>
username: <endpoint_username_for_production_endpoint>
password: <endpoint_password_for_production_endpoint>
sandbox:
enabled: <whether_security_is_enabled_for_sandbox_endpoint>
-----------------------------------------------------------
deploymentEnvironments:
- displayOnDevportal: <boolean>
deploymentEnvironment: <environment_name>
deploymentVhost : <vhost_name>
certs:
- hostName: <endpoint_url>
alias: <certificate_alias>
path: <certificate_name>
mutualSslCerts:
- tierName: <subscription_tier_name>
alias: <certificate_alias>
path: <certificate_name>
policies:
- <subscription_policy_1_name>
- <subscription_policy_2_name>
apictl import api --file
<path-to-API-archive> --environment
<environment>
--preserve-provider=<preserve_provide
r> --update=<update_api>
--skip-cleanup=<skip-cleanup>
--params <environment-params-file>
--rotate-revision

27. 27
Parameters File for an API Product
environments:
- name: <environment_name>
configs: <multiple_configurations_relevant_to_the_specific_environment>
dependentAPIs:
<api_1_name>-<api_1_version>:
endpoints:
-------------------------
<api_2_name>-<api_2_version>:
endpoints:
-------------------------
deploymentEnvironments:
- displayOnDevportal: <boolean>
deploymentEnvironment: <environment_name>
deploymentVhost : <vhost_name>
mutualSslCerts:
- tierName: <subscription_tier_name>
alias: <certificate_alias>
path: <certificate_name>
policies:
- <subscription_policy_1_name>
- <subscription_policy_2_name>
Parameters for an API

28. 28
6. Revolutionized VCS (Version Control System)
Support with Source and Deployment
Repositories

29. 29
Then and Now...
● The facility to combine the CI/CD pipelines with a
widely used Version Control System (VCS) such
as Git has been introduced last year with the
apictl 3.2.0.
● But it had the ability only to control and maintain
one repository with your APIs, API Products and
Applications.
● With the release of apictl 4.0.0, the above-stated
functionality has been enhanced to support two
(2) repositories at once, namely: the Source
Repository and the Deployment Repository.

30. 30
What are these Source and Deployment Repositories?
● Source Repository - A collection of
source code of project directories
without environment specific
information.
⦿ Naming convention -
<API_Name>-<API_Version>
● Deployment Repository - A collection of
directories with environment specific
details.
⦿ Naming convention -
DeploymentArtifacts_<API_Name>-<API_
Version>

31. 31
How to Fit Git Integration into this Structure?
● Both should be Git repositories
● You can maintain Git branches in the
Source Repository with APIs/API
Products/Applications corresponding
to multiple WSO2 API-M environments
you wish.
● You do not need to maintain separate
branches in the Deployment
Repository.

32. 32
1 2 3
SET THE SOURCE AND THE
DEPLOYMENT REPOSITORIES
VCS INIT AND COMMIT THE
CHANGES IN BOTH THE SOURCE
AND THE DEPLOYMENT
REPOSITORIES
PUSH THE CHANGES TO THE
WSO2 API-M INSTANCE
apictl set
--vcs-source-repo-path <path>
apictl set
--vcs-deployment-repo-path <path>
apictl vcs init apictl vcs deploy
Steps for Git Integration

33. Demonstration

34. Question Time!

35. Useful Links
35
Medium - API Integration Essentials
https://medium.com/api-integration-essentials
Medium - Think Integration
https://medium.com/think-integration
WSO2 Documentation - WSO2 API Controller
https://apim.docs.wso2.com/en/4.0.0/install-and-setup/setup/api-controller/getting-started-with-wso2-a
pi-controller
Catalog - WSO2 API Controller
https://apim.docs.wso2.com/en/4.0.0/reference/apictl/wso2-api-controller

36. wso2.com
Thanks!