Migrate from Ballerina API Microgateway to Choreo Connect¶

Earlier versions of the Choreo Connect were named as WSO2 API Microgateway (Ballerina MGW). The final version of API Microgateway is 3.X.X and it is compatible with WSO2 API Manager 3.0 series only. With the release of WSO2 API Manager 4.0.0 Choreo Connect 1.0.0 released as the new version of API Microgateway. This document explains how you can migrate from API Microgateway to the Choreo Connect.

Note

Choreo Connect 4.2.0 is only compatible with WSO2 API Manager 4.2.0.

Feature Comparison (Ballerina MGW vs Choreo Connect)¶

Feature	Ballerina MGW	Choreo Connect
SOAP backends
REST APIs
gRPC APIs
Websocket APIs
Custom mediation/transformation
Advanced throttling (header, IP, query param, JWT claims)
Schema validation
JWT revocation
Per resource endpoints
Custom filters
OAuth2 self-contained tokens
Mutual SSL
Basic Auth
API keys
OAuth2 opaque tokens (Introspect)
Local throttling (node level)

Message Transformation (Request/Response interceptors)¶

API Microgateway v3.x.x¶

Message transformation is possible with request/response interceptors in API Microgateway. Interceptors can be written in the Ballerina or Java programming languages. These interceptors are operative within the gateway. You can obtain more information from here.

Choreo Connect v1.2.0¶

Choreo Connect allows to do message transformation with request/response interceptors. In contrast to the API microgateway, users are required to maintain a separate interceptor microservice. Choreo Connect provides an Open API specification to create a custom request/response interceptor microservice in any programming language. Sample implementations are available in Ballerina, Java, Golang, and Node js. You can obtain more information about Choreo Connect interceptors from here.

Custom filters¶

API Microgateway v3.x.x¶

Filters are execution points in the request and response flow that intercept the request before it reaches the backend service and intercept the response before it reaches the client. Filters are applied to all APIs available via Microgateway. Default filters include authentication, rate limiting, analytics, and so forth. In addition to the default filters, users may create their own custom filters, which can be injected in whatever order they choose. The custom filter can be written in Ballerina language. More information about custom filters available in here.

Choreo Connect v1.2.0¶

The initial version of Choreo Connect only supports request flow that intercept the request before it reaches the backend service. Filters are applied to all APIs available via Choreo Connect. Default filters include authentication, rate limiting, analytics, and so forth. In addition to the default filters, users may create their own custom filters, which can be injected in whatever order they choose. You can obtain more information about Choreo Connect filters from here.

Immutable API Gateway¶

API Microgateway v3.x.x¶

The API Microgateway is intended to function as an immutable API gateway, where you must construct the API Microgateway to update existing deployed APIs. The API microgateway does not allow API hot updates. The custom filter can be written in Ballerina language. More information available in here.

Choreo Connect v1.2.0¶

Choreo Connect is designed to be a mutable API gateway that publishes API modifications in real time. If necessary, it additionally supports the Immutable API gateway, which loads the API projects only during Adapter startup if they are located in /home/wso2/artifacts/apis. The workflow can be created in the following manner.

Commit the API projects to the source version control (eg: Github)
This triggers the CI pipeline such as Jenkins.
It creates the Adapter Docker image placing the API projects in /home/wso2/artifacts/ apis location.
Once the Docker image creation is done, it rolls out the Adapter deployment.
When the new Adapter gets deployed, it deploys the new API or updated APIs in the production environment.

Endpoint Retry Configurations¶

API Microgateway v3.x.x¶

The API microgateway accepts the following configurations for retry policy.

 x-wso2-production-endpoints:
    urls:
      - https://localhost:2380/v3
    advanceEndpointConfig:
      retryConfig:
        count: 1
        intervalInMillis: 1000
        backOffFactor: 1.2
        statusCodes:
          - 504

You can obtain more information about retry and timeout configurations from here.

Choreo Connect v1.2.0¶

Choreo Connect accepts the following configurations for retry policy.

x-wso2-production-endpoints:
    urls:
      - https://localhost:2380/v3
    advanceEndpointConfig:
      retryConfig:
        count: 3
        statusCodes:
          - 504

retryConfig given under prod or sandbox endpoint only has count and statusCode.
Envoy uses a fully jittered exponential back-off algorithm for retries. Therefore the interval between the retries is always a random number. More information available in here.
A param called backOffFactor does not exist in the envoy’s retry interval equation, therefore is not expected in the config.
intervalInMillis can only be configured via envoy route configs (not configurable via header) which is common to both prod and sandbox. Thus, we have made intervalInMillis configurable via a parameter BaseIntervalInMillis in the config.toml which is the base interval for the Envoy's exponential retry back off algorithm.
An upper bound can be set for the retry count taken from all API definitions. It can be set via MaxRetryCount set in config.toml. When the configured retry count in the API definition is larger than the MaxRetryCount, MaxRetryCount will be assigned as the count.
Only a range of (401 - 598) status codes can be used to enable retry. If a status code out of this range is given in an API definition, that status code will get dropped when deploying the API. If this leads to an empty array of status codes, the default status codes configured in config.toml will be used.

Moving APIs from Ballerina MGW to Choreo Connect¶

Standalone Gateway¶

There is no straightforward way to migrate APIs from Ballerina MGW to Choreo Connect. Users need to create the APIs from scratch using the OpenAPI/Swagger definitions.

Using the apictl command line tool, users can generate apictl projects as follows.

apictl init project-1 --oas <Path_to_OpenAPI_File>

Step by step guide includes in here.

Choreo Connect with WSO2 API Manager 4.2.0¶

Choreo Connect v4.2.0 is only compatible with WSO2 API Manager 4.2.0. Hence you need to upgrade to 4.2.0.

Upgrade WSO2 API Manager version to 4.2.0.

A detailed explanation regarding the above includes in here.
Connect Choreo Connect microgateway to API Manager 4.2.0 as a gateway.