Photo by Modestas Urbonas on Unsplash

WSO2 API Controller 4.1.0 was released with WSO2 API Manager 4.1, which supports performing CI/CD tasks for APIs/API Products and Applications alongside WSO2 API Manager.

Early versions of WSO2 API Controller could manage WSO2 API Manager 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 deployment, use as a developer CLI tool for Choreo Connect (API Microgateway), and perform WSO2 Micro Integrator server-specific operations.

This blog will introduce the new features of WSO2 API Controller, its official documentation, and its catalog that contains the abstract view of the commands and their usages.

New Features of WSO2 API Controller 4.1.0

1. CLI Support for per API Logging Feature

API logs assist in observing requests and responses passing through WSO2 API Gateway. Enabling correlation logs affects the efficiency and performance of the server. Hence, API logs can be used to collect HTTP call logs without affecting performance significantly.

By default, the API logs are disabled but can be enabled by using either the DevOps REST API introduced in WSO2 API Manager, or by using WSO2 API Controller. The approach of Per API logging can be divided into subsections as shown in Figure 1.

Figure 1: Per API Logging Feature Division

A new command has been introduced as apictl set api-logging to set the log level per API in an API Manager environment. Supported log-level values are  FULL ,  BASIC ,  STANDARD  and  OFF . The help command output of this command is shown in Figure 2.

Figure 2: “apictl set api-logging” help command output

Another command to retrieve the logging details of APIs or an API in an environment has been introduced as apictl get api-logging, which is shown in Figure 3.

Figure 3: “apictl get api-logging” help command output

Note: The tasks related to the per API logging feature can only be conducted by a user with super admin permissions.

2. Support to change the lifecycle states of API Products using WSO2 API Controller

This was first introduced from WSO2 API Controller 3.1.0 onwards. After that, the support to import/export API Products was introduced in WSO2 API Controller 3.2.0. However, no concept as “API Product Lifecycle states” existed until now.

Consequently, the same ability was introduced in WSO2 API Controller 4.1.0 by introducing a new command named apictl change-status api-product. This is shown in Figure 4.

Figure 4: “apictl change-status api-product” help command output

Moreover, a flag (similar to what we already have for APIs) named  --preserve-status  has been introduced to the apictl export api-product command, that can preserve the API Product lifecycle status when exporting. Otherwise, the 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 the  basic  and the  digest  types,  OAuth 2.0  support plays a major role. WSO2 API Controller 4.1.0 has this feature. A sample API params file with OAuth 2.0 security can be found here.

Maintenance Features and Improvements of WSO2 API Controller 4.1.0

1. Changes to the project structure due to new operation policies 

The new policies feature allows users to attach policies to API operations. These can be request, response, or fault policies. With these architectural changes, the project structure of an exported API project also evolves. 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.yaml

The earlier versions of WSO2 API Controller’s API projects had a folder named Sequences, and is now renamed as Policies. Moreover, the Sequences folder contained  .xml  files, but now the renamed Policies folder contains  .j2  and  .yaml  files. The  .j2  file contains the template of the operation policy, while the  .yaml  file contains the metadata (in other words, the definition of the particular policy). If we consider the  addHeader_v1.j2  content it will look as shown below.

The definitions of the parameterized attributes such as headerName and headerValue above will be inside the  addHeader_v1.yaml  as shown below.

Additionally, the content inside the  api.yaml  file is key. The  operations  field inside this file contains the details about which operation policies are attached to each resource along with the parameterized attribute values (also known as “parameters”).

Similarly, if you want to import an API with attached operation policies, your project must have these three files: 

• A  .j2  template of the operation policy (This can be a  .gotmpl  file as well).
• A  .yaml  file with the policy definition.
• A correctly defined  operations  field with the appropriate 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 previous releases, users were able to substitute environment variables in  .xml  files of sequences. With the new operation policies feature, this support has been given to the  .j2  and  .gotmpl  files. Consider the below example  .j2  content.

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 shown in Figure 5 below.

Figure 5: apictl get apis — format “table {{ jsonPretty . }}”

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. This is shown by Figure 6.

Figure 6: apictl get apis — format “jsonArray”

4. Included an Alpine Docker image build

You can build a Docker image of WSO2 API Controller as mentioned here under the section, Building a Docker Image of APICTL, and use it in a containerized environment.

Conclusion

As you can see, with these new features and improvements, WSO2 API Controller has the necessary requirements to further improve CI/CD capabilities. Feel free to explore more and get started with WSO2 API Controller, find out more about WSO2 API Controller (check its commands catalog here), or join our Slack channel to directly ask our developers regarding your issues, comments, or concerns about the product.