5 Jan, 2022 | 3 min read

Introducing Choreo Connect 1.0.0

  • Pubudu Gunatilaka
  • Senior Technical Lead - WSO2

Choreo Connect is a cloud-native, open-source, and developer-centric API gateway. It provides first-class support for Kubernetes while facilitating an array of API management quality of services (QoS), such as message security, rate-limiting, observability, and message mediation. As a microgateway, it provides additional flexibility, scalability, and resilience to meet today's cloud native demands. Powered by Envoy proxy, the solution can handle billions of transactions each day, due to its high throughput, low latency, and small footprint. It supports protocols like REST and Websocket. Now, you can protect your APIs, future-proof apps, and monetize digital assets with robust OOTB features. Choreo Connect can be run in the cloud, on-premises, or in a hybrid environment, as long as it supports Kubernetes.


Choreo Connect comprises three components: Router, Enforcer, and Adapter. 


The Router is the component in charge of directing traffic from various clients to the intended destination (service). Choreo Connect uses the Envoy Proxy as the core component for traffic routing. The Router is key to exposing APIs to external and remote clients.


When the Router receives a request, it sends it to the Enforcer, which applies API management features such as security, rate limiting, analytics, and other validations. It responds to the Router when the Enforcer has completed its validation. The Router will route the request to the real backend if the response is an allowed response; if not, if the response is a denied response, the Router will send a reply back to the client with an error message.


Both the Router and the Enforcer use the Adapter as their control plane. It converts API information into language that the Router and Enforcer can understand. It turns API information into clusters and routes for the Router. It translates API information into a predetermined data model for the Enforcer. A Data Plane API is available for the Router and Enforcer, which can be used to dynamically configure them. 

Choreo Connect Modes

  • Choreo Connect with WSO2 API Manager as a Control Plane

Choreo Connect can use WSO2 API Manager as its control plane, whether it's in the cloud or on-premises. As a result, user operations such as API deployment, application creation, key generation, and subscription creation can be seamlessly received.

  • Choreo Connect as a Standalone Gateway

Without WSO2 API Manager as the control plane, Choreo Connect can be deployed as a standalone gateway. APICTL is a command-line program that can be used to deploy APIs. By incorporating the OpenAPI specifications in APICTL, it is possible to develop API projects. 

What’s New in Version 1.0.0?

API Manager as a Control Plane

The Choreo Connect Microgateway is designed to connect to any API Manager control plane that runs anywhere. This allows you to deploy and manage a variety of APIs, including REST, websockets, and prototypes from the control plane. Choreo Connect 1.0.0 is compatible with API Manager 4.0.0. 

It allows testing APIs with internal test keys via the WSO2 API Manager Publisher portal, in addition to controlling the API lifecycle via WSO2 API Manager. You may apply numerous settings to APIs using the API Manager control plane, such as CORs, security, rate limitation, mediations, and so on, while it also controls API accessibility via blocking/unblocking subscriptions.

You can utilize separate virtual hosts to expose APIs while managing several gateway environments. The Choreo Connect microgateway can interact with multiple key managers, which may be added using the API Manager Admin portal.

As a Standalone Gateway

Choreo Connect can be deployed as a standalone gateway and use the APICTL command line tool to deploy APIs. APICTL can be used to create API projects by incorporating OpenAPI specifications. These API projects can be pushed to the Adapter directly, and it gets deployed in the Enforcer and Router. The following command deploys an API in Choreo Connect. 

apictl mg deploy api -f petstore -e dev

When used as a standalone gateway, Choreo Connect can be used with an external Secure Token Service (STS), which will provide signed JWTs, and Choreo Connect will validate those JWTs in the incoming requests. In order to achieve subscription validation, we need to have subscription data also included in the incoming authentication JWT, which is called as a self-contained token.

Choreo Connect can also be used as an immutable gateway that only accepts API projects upon startup. The API projects should be placed in the Adapter's artifact directory in this approach. You may also deploy Adapter Docker images that include the API projects as part of the Adapter's Docker image.


Protocols such as OAuth2 (JWT access tokens) and API Keys can be used to secure APIs. These tokens can also be revoked. Connecting to WSO2 API Manager as the control plane allows you to perform subscription validations for APIs. Choreo Connect also supports self-contained access tokens, which contain subscription data inside the JWT itself. This functionality is useful for deploying Choreo Connect in a locked down environment, where it does not have access to WSO2 API Manager for control instructions. Not only does Choreo Connect offer authentication, but it also allows you to authorize APIs using scopes. The backend JWT approach is used by the microgateway to send end-user information to the backend services. Users are able to write their own custom backend JWT generator. 

Rate Limiting

Rate limiting allows users to limit the number of incoming requests to Choreo Connect. To publish and receive throttling data, Choreo Connect connects to WSO2 API Manager’s Traffic Manager component. The process is known as global throttling. Choreo Connect supports API level, resource level, subscription level, and application level rate limiting.

Certain APIs may demand a more detailed degree of Rate Limiting in some cases. Assume you wish to provide a certain IP range or kind of client application restricted access (identified by a user-agent header). A basic throttle policy with API/resource level constraints is insufficient in such an instance. Choreo Connect can rate limit requests depending on a variety of circumstances, including particular IP or IP ranges, headers, query parameters, and JWT claims, to solve complicated throttling requirements like those mentioned above. 

Choreo Connect allows you to create custom rate limiting policies that apply to the whole system. When administrators need to establish dynamic rules for specific usage circumstances, this feature comes in handy. Using WSO2 API Manager as the control plane, it can control access to specific APIs, applications, specific IP addresses and a user. 

Mediation and Message Transformation

The request/response interceptors in Choreo Connect provide mediation and message transformations. Before forwarding the request to the backend, the request interceptor is activated. Before responding to the client, the response interceptor gets triggered. An interceptor is a separate microservice that handles request, response, or both request and response transformations. 

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. Interceptors can be defined at the API level (per API) and at the resource level (per resource). The request flow from the client to the backend via the request interceptor service and the response flow from the backend to the client via the response interceptor service are depicted in the diagram below.

Service Discovery

In a microservices architecture, the operating service endpoints are usually not static. A service can have several upstream endpoints. As a result, services must employ a service discovery approach to locate other services' upstream endpoints. Consul service registry is supported by Choreo Connect for service discovery, allowing upstream services to be identified automatically. It also has a Consul service mesh integration for service discovery. In an environment where Consul is utilized as a service mesh, Choreo Connect may be used as an ingress gateway to expose APIs or services to developers or API users while providing security, rate restriction, and other QoS.


Load balancing and failover endpoints are natively supported in Choreo Connect. When you apply Load Balanced API Endpoints, traffic to the resource is routed using a round-robin mechanism to the stated endpoint addresses. Failover Endpoints guarantee that consumers have a consistent API invocation experience even if a single API Endpoint has a failure. Additionally with dynamic endpoint support, you can execute some logic in the request interceptor and derive the backend endpoint for sending the request.

For different reasons, such as load or a momentary problem, the backend endpoint may be unavailable for a brief period of time. In such cases, Choreo Connect configures a Retry Policy, which instructs the router to retry the HTTP request on behalf of the client. Endpoint timeouts can also be defined using the microgateway. The Timeout specification will allow the client to receive a timely response whenever a backend endpoint takes an unusual amount of time to react.

Endpoints can be secured using Basic Authentication and Mutual TLS when it comes to endpoint security.

API Insights and Observability

Choreo Connect can publish events to the Choreo platform, which can be used to generate analytics. For the APIs deployed on Choreo Connect, Analytics provides reports, dashboards, statistics, and graphs. Choreo Connect may also be set up to publish analytics data to any third-party solutions.

To self-sufficiently emit the present status of the system, generate alerts for any irregularities identified to proactively identify failures, and offer information to investigate the underlying causes of a system failure, observability is a critical need. With Jaeger, Zipkin, and Azure App Insights, Choreo Connect provides open tracing.


The Choreo Connect microgateway has a single configuration file to configure the Adapter, Router, and Enforcer. The Adapter manages the configurations and passes relevant configurations to the Router and Enforcer. There are separate logging configuration files for the Adapter/Router and Enforcer. As these logging configurations apply at runtime, it helps to troubleshoot any issues in a production system. In addition to the configuration file, users are able to provide configurations via environment variables that have the CC prefix as follows.



Filters are a set of request flow execution points that intercept requests before they reach the backend service. They are engaged while the enforcer processes the request. All APIs deployed in Choreo Connect are subjected to the given set of filters. In addition to the built-in filters such as authentication and throttling, users can implement their own custom filters.


When designing the Choreo Connect microgateway, troubleshooting is considered an important event. When issues occur during runtime, the Router responds with particular error codes that help to pinpoint the problem. These error codes can be related to upstream related failure, intra component connection failure, interceptor service related issues, and so on.

An Admin REST API is provided in Enforcer for troubleshooting purposes, and it can be used to retrieve API, application, subscription, throttle policy, and revoked tokens related information. Users can identify the specific root cause of errors occurring in the API invocation flow using this information.

Check it Out!

To try Choreo Connect, go to our website and download it. The website includes contact information as well as instructions for joining our Slack channel.