Say Hello to the New and Improved Choreo Experience!


Choreo by WSO2 is a cloud native Integration Platform as a Service (IPaaS) for API developers. It was released as a public beta last year.

Choreo underwent some major improvements recently. These include improvements to the development experience, user interfaces, component development flows, etc..

In this tutorial, I would like to take you through these changes step by step, so that you can easily switch to the new version of Choreo. This tutorial does not require you to have any prior experience using Choreo. So even if you are completely new to Choreo, you can still follow along. And at the end of this tutorial, you will have your first API deployed and ready to accept traffic.

To get started, let’s first login to the Choreo console.

In the latest version of Choreo, Identity Management is powered by Asgardeo. Asgardeo is a new IDaaS by WSO2 that was also introduced recently.

Therefore when we log into Choreo, we will now be prompted to authorize Asgardeo.

If you are signing into Choreo for the first time, you will be prompted to create an organization before being redirected to the home page of the Choreo console.

Provide a preferred name for the organization and click create.

Every Choreo user will have their own organization. However a user is not limited to a single organization and can be a member of multiple organizations as well.

If you have used Choreo before, you would have already created an organization and therefore you will be taken to the home page of the Choreo console directly. The home page of the Choreo console is shown below.

Choreo console Home

The overall layout of the console is similar to the previous version of Choreo (which will be referred as the legacy version from this point onwards). However, there are improvements to the User Interface.

One of the new features in Choreo is the concept of Projects.
A Choreo project can be thought of as a software project that you are working on. You can create components within a project.
There can be multiple projects and each project can have multiple components. Organizing components into projects will make it easier to manage them.

There can be multiple projects within a Choreo organization. And each project can have multiple components in it. This relationship between Organizations, projects and components in Choreo can be depicted as follows.

Relationship between Organizations, Projects and Components

We will have a “Default Project” created for us already. But if we want to create a new project, we can do so by clicking on the Project selector at the top and clicking the “+ Create New” button as shown below.

Project selector

If you have used the legacy version of Choreo, you may have already created some applications. If so, you will see the following banner in the console home page.

Migration banner

We can migrate these applications from the legacy Choreo version to the latest version with ease.

Click “View apps in the legacy version” link to open the legacy console of Choreo to check the applications you already have. Migrating them to the latest version can be done by clicking the “Migrate” button in the above banner. Clicking it will start the migration process which will run in the background and notify you once the process is complete.
You can read more about the migration process in this migration guide.

Once the migration is complete, make sure to change the project to view the migrated components.

Migrated component list

Let us now see how we can create a component of API type, deploy and invoke it in the new Choreo console. The easiest way to get started is to use one of the Samples.

From the home page, click the “View All” link in “Use a sample and get started” section to list all the samples.

Choose a sample you wish to use, click “Get started” and wait for Choreo to create an API type component from it.

I will be using the COVID-19 Statistics sample for this tutorial.
The COVID-19 Statistics sample responds with COVID-19 statistics for any given country.

Choreo Samples
Creating an API from a sample

Once the component is created, we will be redirected to the following page. This is the “Develop” page where we develop the API component we just created.

Component Develop view

When compared to the legacy console ’s “Develop” page, this latest version has several new sections. Let me explain what each numbered section in the above image is.

i — This menu is used to navigate to each step in the component development workflow. We start off in the “Develop” page where we develop the component. This is where we use either code or low-code to develop the component. Once we develop it, we will deploy it. So we navigate to the “Deploy” page. Once deployed, we will “Test” it and so on. Simply follow the steps marked by the arrows to follow the workflow.

ii — Whenever we do any development in the component, our changes should be committed to a Git repository. The list of commits appear here.

iii — In the legacy Choreo console, there was a text editor for code editing and a separate editor for low-code editing. Now both these are integrated into a Visual Studio Code editor running in the browser. This new VSCode editor provides a much better experience when developing Choreo components. Click this button to open the VSCode editor.

iv — This section shows the low-code diagram of the component. We can select different commits (from the list in ii) to see how the low-code diagram changes accordingly.

v — This section shows an overview of the component. We have the ability to add a description or labels to our component through this section.

Let us now open the VSCode editor and do some changes to our component. Click the “Edit with VSCode Online” button to get started.

Editing the API code from the VS Code editor

Once the code editor opens, click the “Explorer” button on the left navigation bar and open the file named “sample.bal”. This is the file containing the code of our component. We can edit our component from this editor.

I will import the ballerina/log library and add a new info log to the resource function. This will cause a line to be logged for every successful request to the API. Refer the image below for the changes.

Once the changes are done, we need to commit them to a Git repository. As Choreo users, we do not need to worry about initializing a Git repository or configuring Git remotes for our component. All this has been handled by Choreo when we started working on the component.

Staging, committing, pushing and any other version control actions can be done using the source control menu of VS Code. Let me take you through the steps in case you are not familiar with this interface.

Staging and committing the changes using the source control menu

i —Open the source control menu

ii — Open the file and verify the changes. We can see a diff of the changes when we open the file.

iii — Stage the changes by clicking the ‘+’ sign

iv — Type a commit message and commit the change

Next, we need to push our changes to a remote Git repository as shown below.

Pushing the changes to a remote Git repository

Now that we have edited the component as required, let’s go back to the Choreo console. The change we did is now reflected in the “Develop” page.

Develop page after editing the code

Now that we have developed our component, we are ready to deploy it. To do so, let’s navigate to the “Deploy” page.

Deployments are another area that has undergone a major change in the new version of Choreo. Previously, after we developed a Choreo application, we had the ability to run it in a special test environment. But in the latest version of Choreo, a concept of environments have been introduced and we can deploy our changes to these environments.

When we deploy a component, it will first get deployed to a development environment. We can test the changes in the development environment. Once we are satisfied with them, we can promote them to the production environment.

Let me show you how it works. Click the “Deploy” button indicated by the arrow in the image below to deploy the component to the Development environment.

Deploy page of the component

Once the deployment process begins, we will see a breakdown of what is happening and their progress.

Development environment deployment progress

When the deployment to the development environment is complete, we can test our changes. We can do so by clicking the “Test” button which will take us to the “Test” page.

Button to navigate to the test page

Testing can be done using the OpenAPI Console, cURL or Postman. For this tutorial, let’s use the OpenAPI Console.

Click the “Get Test Key” button to generate a key for testing. Next click the “GET” method to expand the testing console and specify the input parameter. The COVID-19 Statistics API expects the country whose statistics we wish to see. It needs to be provided as a country code. I am going to provide “CH”, the country code of Switzerland as the parameter.
Finally, click the “Execute” button to invoke the testing endpoint.

Testing using the OpenAPI Console

This will cause our API deployed in the development environment to be invoked. If it is successful, we should see a response as shown in the image below.

Response when testing the API using the OpenAPI console

Now that we have verified that our API is working, we are ready to promote it to the production environment. To do so, let’s go back to the deploy page and click the “Promote” button under the Development environment section.

Promoting changes from the development environment to the production environment

Once the API is deployed to the production environment, we should see a screen as follows.

Successful deployment to the production environment

We can now use any method to invoke the production API. Click the “Test” button under the Production deployment to navigate to the “Test” page again. Let’s use the cURL command to invoke the API this time.

We can copy the generated curl command from the “Test” page and run it.

cURL command generated by the Test page
Invoking the production endpoint using the curl command

If you see a successful response like the one shown above, it means that you have successfully deployed an API in a production ready manner!

We cannot simply deploy an API and forget about it. This is because we need to observe how it behaves.
What sort of a throughput does the API have? Are there latency spikes? Are there any errors in the logs? are some questions we would have after deploying an API. These questions and much more can be answered using the “Observe” page of the component in the Choreo console.

The images given below show how the “Observe” page looked like after I invoked the production endpoint. (If you look closely, you will notice some errors in my API. This is because I intentionally sent incorrect country codes with my requests)

And if you look at the logs at the bottom right, the log line I added when developing the component can be seen.

Observe page of the component

Choreo observability can also be used to diagnose problems with Choreo components. Click the “Diagnostics view” tab to understand how resources were utilized by our component. We can also select a section of time and click the “Flamegraph” button to view a flamegraph.

Diagnostic view in the Observe page


In this tutorial, I explained some of the new features that were recently introduced in Choreo. I also showed how to develop, deploy and test an API using the latest version of Choreo.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store