Encanto with WSO2 APICTL 4.1.0
You’re Exactly what this Family Needs
On the 11th of April 2022, with the release of WSO2 API Manager (WSO2 API-M) 4.1.0, another sibling was born as the API-M family member to perform CI/CD tasks for APIs/API Products and Applications, which is WSO2 API Controller (apictl) 4.1.0.
Early versions of apictl had the capabilities to manage API-M environments, list APIs, API Products and Applications, create API projects, import/export APIs, API Products and Applications, generate tokens for APIs and API Products for testing purposes, manage APIs on a Kubernetes (k8s) deployment, use as a developer CLI tool for Choreo Connect (API Microgateway) and perform WSO2 Micro Integrator (WSO2 MI) server-specific operations.
This article will take you through a tour by introducing new changes done with apictl 4.1.0. You can download the apictl 4.1.0 from this link and the official documentation can be found here. The catalogue of apictl is included here which contains the abstract view of the commands and their usages.
New Features of apictl 4.1.0
1. CLI support for the per API logging feature
API logs assist in observing requests and responses passing through WSO2 API Gateway. Enabling correlation logs affects the efficiency and the performance of the server. Hence, API Logs can be used to collect HTTP call logs without a considerable performance hit.
By default, the API logs are disabled but can be enabled either using the DevOps REST API introduced in WSO2 API-M 4.1.0, or by using apictl 4.1.0.
A new command has been introduced as apictl set api-logging to set the log level per API in an API-M environment. Supported log-level values are FULL, BASIC, STANDARD and OFF .
Another command to retrieve the logging details of APIs or an API in an environment has been introduced as apictl get api-logging.
Note that, the tasks related to the per API logging feature can be only performed with a user who has super admin permissions (A user with the admin role in the super tenant: carbon.super).
2. Support to change the lifecycle states of API Products using apictl
The support to change the life cycle states of APIs was introduced from apictl 3.1.0 onwards. After that, the support to import/export API Products was introduced in apictl 3.2.0. However, there was no concept known as “API Product Lifecycle states”, until the release of WSO2 API-M 4.1.0.
Consequently, the same ability was introduced in apictl 4.1.0 by introducing a new command named apictl change-status api-product.
Moreover, a flag (similar to what we already have in APIs) named
--preserve-statushas been introduced to the apictl export api-product command, that has the ability to preserve the API Product lifecycle status when exporting. Otherwise, API Product will be exported in the CREATED state.
3. Supporting OAuth 2.0 endpoint security via API parameters file
When configuring endpoint security, similar to thebasic and the digest types, the OAuth 2.0 support plays a tremendous role. Hence, apictl 4.1.0 has incorporated this ability. A sample API params file with OAuth 2.0 security can be found here.
Maintenance Features and Improvements of apictl 4.1.0
1. Changes to the project structure due to the new operation policies feature
The new policies feature allows the users to attach policies to API operations. Those can be request, response or fault policies. With these architectural changes, the project structure of an exported API project also evolved. Below is the structure of an API that has operation policies attached, which was exported using the apictl export api command.
PizzaShackAPI-1.0.0
├── api_meta.yaml
├── api.yaml
├── Definitions
│ └── swagger.yaml
├── deployment_environments.yaml
└── Policies
├── addHeader_v1.j2
├── addHeader_v1.yaml
├── addLogMessage_v1.j2
└── addLogMessage_v1.yamlThe earlier versions of apictl API projects had a folder named Sequences. It has been renamed to Policies with this feature. Moreover, the Sequences folder contained .xml files, but now the Policies folder contains .j2 files and .yaml files. The .j2 file contains the template of the operation policy, while the .yaml file contains the metadata. If we consider the addHeader_v1.j2 content it will look like below.
<property action="set" name="{{headerName}}" value="{{headerValue}}" scope="transport" />The definitions of the parameterized attributes such as headerName and headerValue above will be inside the addHeader_v1.yaml as shown below.
type: operation_policy_specification
version: v4.1.0
data:
category: Mediation
name: addHeader
version: v1
displayName: Add Header
description: This policy allows you to add a new header to the request
applicableFlows:
- request
- response
- fault
supportedGateways:
- Synapse
supportedApiTypes:
- HTTP
policyAttributes:
-
name: headerName
displayName: Header Name
description: Name of the header to be added
validationRegex: "^([a-zA-Z_][a-zA-Z\\d_\\-\\ ]*)$"
type: String
allowedValues: []
required: true
-
name: headerValue
displayName: Header Value
description: Value of the header
validationRegex: "^([a-zA-Z\\d_][a-zA-Z\\d_\\-\\ ]*)$"
type: String
allowedValues: []
required: trueAnother important thing is the content inside the api.yaml file. The operations field inside this file contains, “How the operation policies are attached to a particular operation(s)? and “What are the values of the parameterized attributes?”
operations:
-
id: ""
target: /order
verb: POST
authType: Application & Application User
throttlingPolicy: Unlimited
scopes: []
usedProductIds: []
operationPolicies:
request:
-
policyName: addHeader
policyVersion: v1
policyId: 02240180-ce15-4f99-8995-8fbeb5231ace
parameters:
headerName: HeaderName
headerValue: HeaderValue
response: []
fault: []
-
id: ""
target: /menu
verb: GET
authType: Application & Application User
throttlingPolicy: Unlimited
scopes: []
usedProductIds: []
operationPolicies:
request: []
response:
-
policyName: addLogMessage
policyVersion: v1
policyId: 41f51ca3-90b7-46b0-baba-0c539578c0aa
parameters: {}
fault: []Similarly, if you want to import an API with attached operation policies, your project should have the below three (3) contents.
.j2template of the operation policy (This can be a.gotmplfile as well).yamlfile with the policy definition- Correctly defined
operationsfield with the correctly attached operation policy details
2. Changes to the dynamic environment variables support
The main change in the dynamic variables support is related to operation policies. In the previous releases, the users were able to substitute environment variables in .xml files of the sequences. With the new operation policies feature, this support has been given to the .j2 or .gotmpl files. Consider the below example .j2 content.
<sequence xmlns="http://ws.apache.org/ns/synapse" name="custom-header-in">
<header name="X-ENV-KEY" value="${ENV_KEY}" scope="transport" />
<log level="custom">
<property name="Sent header(X-ENV-KEY)" value="${ENV_KEY}"/>
</log>
</sequence>In the above file, ${ENV_KEY} symbolizes an environment variable. The notation is similar to the previous releases.
3. Introduced a new format such as “jsonArray” to list down APIs as a JSON array
When you use --format “table {{ jsonPretty . }}” with apictl get apis, the output is returned as below.
The above output does not contain the results in a JSON array. Hence, a new format type has been introduced as "jsonArray" to cater this requirement.
4. Included an Alpine Docker image build
You can build a Docker image of apictl as mentioned here under the section Building a Docker Image of APICTL and use it in a containerized environment.
Last but not least…
With the above-mentioned features and improvements, we can see that apictl has evolved more with many features and improvements that are needed for CI/CD.
Before wrapping things up, I would like to suggest you something. You can be a newbie to the apictl or not, try to explore this more with our official documentation that can be found in the below links.
You can also join the official WSO2 API-M slack channel (wso2-apim.slack.com) via this for better communication. You can talk to the developers directly regarding any issues, or concerns about the product. We encourage you to start discussions or join any ongoing discussions with the team, via our slack channel.
Goodbye until the next time…. Stay safe everyone. Happy exploring!!
