Deep Dive into APICTL 3.2.4 with Advanced Endpoint Configurations

WSO2 API Controller 3.2.4 + WSO2 API Manager 3.2.0

Glad tidings to all the WSO2 API Manager (WSO2 API-M) 3.2.0 fans! WSO2 API Controller (apictl) 3.2.4 which was released on 14th October 2021, is the newest member of apictl 3.2.x family that is compatible with WSO2 API-M 3.2.0. Major improvements of apictl 3.2.4 include,

• The support to override OAuth 2.0 endpoint security using the parameters file.

Configuring Different Endpoint Security Types - WSO2 API Manager Documentation 3.2.0

• The support to configure advanced endpoint configurations of an API using the parameter (api_params.yaml) file for REST/SOAP endpoints.

Configuring Environment Specific Parameters - WSO2 API Manager Documentation 3.2.0

In this article, I am going to deep dive into,

Setting the advanced endpoint configurations for load balanced and failover endpoints using apictl 3.2.4 for REST/SOAP endpoints

Still, you didn’t get what I said? Not to worry, I will explain this precisely.

Come Along!!!

Come Along!!!

Wondering what does “Advanced Endpoint Configurations” mean and the apictl’s role here?

WSO2 API-M 3.2.0 allows you to control the production and sandbox endpoints using the Advanced Endpoint Configurations such as Endpoint Suspend State (Error Codes, Initial duration, Max duration, Factor), Endpoint Timeout state (Error Codes, Retries Before Suspension, Retry Delay), Connection Timeout (Action, Duration) as mentioned here. Previous apictl 3.2.x releases did not have the ability to set the above-stated configurations using the parameters (api_params.yaml) file. This support has been introduced with the apictl 3.2.4 in a much more enhanced manner to cater for your needs.

Moreover, WSO2 API-M 3.2.0 supports a range of different endpoint types such as REST, SOAP, Dynamic, AWS Lambda, allowing the API Gateway to connect with advanced types of back-ends. Furthermore, to support high availability for endpoints, the endpoint routing policies such as load balancing and failover can be used.

apictl 3.2.4 assists us to do the tasks explained in the above two (2) paragraphs in a collaborative manner. Simply, this article explains the way to configure advanced configurations for REST/SOAP endpoints using the parameter file via apictl 3.2.4 for high-availability endpoint routing policies such as load balanced and failover.

Still curious?

How about doing a demonstration with some examples of parameter files which you can use as references when trying this out?

Agreed? I’ll start.

First and Foremost… Prerequisites

Under the assumption that you have already installed Oracle Java SE Development Kit (JDK) version 11.\* or 1.8.\* and set the JAVA_HOME environment variable (For more information on setting the JAVA_HOME environment variable for different operating systems, see Setup and Install) you need to satisfy the below requirements.

• Download and set up WSO2 API-M 3.2.0 (I will be using a U2 updated API-M 3.2.0 pack for the demonstration. For more information on how to update using U2, see Updates 2.0 Documentation.)
• Start WSO2 API-M 3.2.0 server
• Download and initialize apictl 3.2.4 (Make sure to add an environment named “dev”, since I will be using it during the demonstration)
• Initialize an API project or export an existing API Project from a WSO2 API-M instance. For the demonstration purpose, I will be initializing an API project so that we can use it in future.

./apictl init Petstore --oas https://petstore.swagger.io/v2/swagger.json

The initialized API project will have the below structure and what we are focussing on is the api_params.yaml file content. We can modify the content of that to set advanced endpoint configurations for the particular API.

Petstore
├── api_params.yaml
├── Docs
│   └── FileContents
├── Image
├── Interceptors
├── libs
├── Meta-information
│   ├── api.yaml
│   └── swagger.yaml
├── README.md
└── Sequences
    ├── fault-sequence
    ├── in-sequence
    └── out-sequence

Let’s Begin…

This section will be divided into three (3) subsections based on the three (3) main user stories that I am going to discuss.

1. Setting Advanced Endpoint Configurations for REST/SOAP endpoints “without load balancing or failover” using apictl
2. Setting Advanced Endpoint Configurations for REST/SOAP endpoints “with load balancing” using apictl
3. Setting Advanced Endpoint Configurations for REST/SOAP endpoints “with failover” using apictl

1. Setting Advanced Endpoint Configurations for REST/SOAP endpoints “without load balancing or failover” using apictl

This is the simplest scenario that we encounter when setting the advanced endpoint configurations without high availability endpoint routing policies such as load-balanced or failover. Check the below api_params.yaml content.

Note that, the above example is for a REST endpoint type as specified by the field endpointType . You can change this to SOAP as well if you need SOAP endpoints to be set.

Anyway, let’s import the API which we created in the Prerequisites section along with the above parameter file content.

./apictl import-api -f Petstore -e dev --params api_params_advanced_ep_configs_3.2.4_without_load_balance_failover.yaml

Now, login to the WSO2 API-M Publisher Portal and click on the imported API. Go to the Endpoints section you can see that the endpoints have been set.

Overriden Endpoints without load balancing or failover routing policy

If you click on the Settings icon of each of the endpoints, you can see that the advanced endpoint configurations have been set as expected.

2. Setting Advanced Endpoint Configurations for REST/SOAP endpoints “with load balancing” using apictl

In this topic, I will be showing you how to set the advanced endpoint configurations when the endpoint routing policy is Load-balanced. Check the below api_params.yaml content.

As explained before, the above example is for a REST endpoint type as specified by the field endpointType . You can change this to SOAP as well if you need SOAP endpoints to be set.

Anyway, let’s import the API which we created in the Prerequisites section along with the above parameter file content.

./apictl import-api -f Petstore -e dev --params api_params_advanced_ep_configs_3.2.4_with_load_balance.yaml

Now, login to the WSO2 API-M Publisher Portal and click on the imported API. Go to the Endpoints section you can see that the load-balanced endpoints have been set.

Overriden Endpoints with load balancing routing policy

If you click on the Settings icon of each of the endpoints, you can see that the advanced endpoint configurations have been set as expected.

Main Production and Sandbox endpoints

Production and Sandbox load balanced endpoints

3. Setting Advanced Endpoint Configurations for REST/SOAP endpoints “with failover” using apictl

In this topic, I will be showing you how to set the advanced endpoint configurations when the endpoint routing policy is Failover. Check the below api_params.yaml content.

As explained before as well, the above example is for a REST endpoint type as specified by the field endpointType . You can change this to SOAP as well if you need SOAP endpoints to be set.

Anyway, let’s import the API which we created in the Prerequisites section along with the above parameter file content.

./apictl import-api -f Petstore -e dev --params api_params_advanced_ep_configs_3.2.4_with_failover.yaml

Now, login to the WSO2 API-M Publisher Portal and click on the imported API. Go to the Endpoints section you can see that the load-balanced endpoints have been set.

Overriden Endpoints with failover routing policy

If you click on the Settings icon of each of the endpoints, you can see that the advanced endpoint configurations have been set as expected.

Main Production and Sandbox endpoints

Production and Sandbox failover endpoints

Conclusion… Tips and Tricks

Are you wondering how are you going to keep the above-stated facts about the advanced configurations in your mind? Or else, you may need to refer to this article whenever you need to set up the configurations. Oh, don’t worry. Now, I am going to tell you some tips that you can keep in your mind so that you can do these configurations with just a snap of your fingers.

Remember,

• First, the advanced endpoint configurations should be defined under the config field of the parameters file which should always reside below the url field for each endpoint.

url: https://dev1.sandbox.wso2.com
config:
    factor: 4
    suspendMaxDuration: 35000
    suspendDuration: 40000
    suspendErrorCode: 
        - "101001"
        - "101508"
    retryTimeOut: 50000
    retryDelay: 33000
    retryErroCode:
        - "101000" 
        - "101506"
    actionSelect: fault
    actionDuration: 75000

• Second, theoretically, the advanced endpoint configurations can be subdivided into three (3) sections as shown below.

• Third, the advanced endpoint configurations can be set for either REST or SOAP endpoint types. You just need to define the endpointTypein the parameters file.

That’s all. Easy, isn’t it?

In this article, we deep-dived into apictl 3.2.4 by discovering the tips and tricks to configure the Advanced Endpoint Configurations using the parameters file. Now it's time for you to dive alone. Not to worry, I will always be there for you guys if you need any assistance.

Thanks and Goodbye until the next time…

Stay safe everyone!

References

Endpoint Timeouts - WSO2 API Manager Documentation 3.2.0

Getting Started with WSO2 API Controller - WSO2 API Manager Documentation 3.2.0