Skip to content

Deploying a REST API in Choreo Connect

You can deploy a REST API in the following ways depending on the Choreo Connect mode you have chosen.

Mode Method
Choreo Connect with WSO2 API Manager as a Control Plane Via WSO2 API Manager Publisher Portal
Choreo Connect as a Standalone Gateway Via apictl for Standalone Mode

Via WSO2 API Manager Publisher Portal

Follow the instructions below to deploy a REST API in a Choreo Connect instance run with WSO2 API Manager as the Control Plane.

Before you begin

This guide assumes that you already have a Choreo Connect instance configured to run with API Manager. If not,

Step 1 - Create an API in API Manager

Create a REST type API using one of the following methods:

For this example, let's create an API via the WSO2 API Manager Publsiher Portal.

Step 2 - Deploy the API in API Manager

The guide here will explain how you could easily deploy the API you just created.

That's it! To invoke the API follow the steps here.

Info

During the startup, Choreo Connect will check the config.toml to see if the controlPlane configuration has been enabled. If so, it will start fetching all the necessary artifacts that belong to the Gateway environment given in environmentLabels. These artifacts include deployed APIs, Applications, Subscriptions, Policies, information related to Key Managers, etc.

Whenever a new event occurs in API Manager such as an API being deployed, API Manager will notify Choreo Connect via Event Hub. Choreo Connect will then start fetching all the new artifacts related to its environment.

Tip

To be able to invoke an API via the Developer Portal TryOut Console, make sure at least one of the certificates used by the enforcer is same as the certificate used by the Key Manager configured in API-M. In Choreo Connect, the certs for enforcer are located at <CHOREO-CONNECT_HOME>/docker-compose/resources/enforcer/security/truststore. In API-M, Key Managers can be configured from the API-M Admin Portal.

Step 3 - Invoke the API

After the APIs are exposed via Choreo Connect, you can invoke an API with a valid access token.

Let's use the following command to generate a JWT to access the API, and set it to the variable TOKEN. 

TOKEN=$(curl -X POST "https://localhost:9095/testkey" -d "scope=read:pets" -H "Authorization: Basic YWRtaW46YWRtaW4=" -k -v)
Execute the following cURL command to Invoke the API using the access token.

curl -X GET "https://<CHOREO-CONNECT_ROUTER_HOST>:<CHOREO-CONNECT_ROUTER_PORT>/<API-context>/<API-resource>" -H "accept:application/xml" -H "Authorization:Bearer $TOKEN" -k

curl -X GET "https://localhost:9095/v2/pet/findByStatus?status=available" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k

Refer to Generate a Test JWT for more details.

Via apictl for Standalone Mode

Follow the instructions below to deploy a REST API via WSO2 API Controller (apictl), which is a CLI Tool used when Choreo Connect is run as a Standalone Gateway.

Before you begin

This guide assumes that you already have a Choreo Connect instance that is up and running. If not, checkout the Using Choreo Connect Deployed on Docker with WSO2 API Controller Guide on how to install and run Choreo Connect. To learn more about Choreo Connect, have a look at the Overview of Choreo Connect.

Step 1 - Download apictl and Set the Path Variable

First download apictl locally and extract it into a folder of your choice. Then, add its location to your PATH variable.

export PATH=$PATH:<directory-of-the-apictl-executable>

Step 2 - Create an API Project using apictl

Let's create your first project "petstore" using an OpenAPI definition. The following apictl init command will generate a project folder containing all the necessary files.

Warning

If you have used a previous version of apictl before, remember to delete the directories .wso2apictl and .wso2apictl.local that are located in your home directory. Deleting them will make the newer apictl create them again, with content compatible with the current version.

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

Step 3 - Add a Choreo Connect Environment to apictl

To use apictl for Choreo Connect, a Choreo Connect environment needs to be added to apictl. This environment will hold the adapter URL for further commands.

apictl mg add env dev --adapter https://localhost:9843

Info

Note mg in the above command. The apictl commands that starts as apictl mg are Choreo Connect specific. If a command does not have mg after apictl then the command could probably be common to both Choreo Connect and API Manager, but it could also be API Manager specific.

Tip

The apictl commands here onwards are executed with the -k flag to avoid SSL verification with the Choreo Connect.

To communicate via HTTPS without skipping SSL verification (without -k flag), add the cert in the Choreo Connect truststore into the <USER_HOME>/.wso2apictl/certs folder.

Step 4 - Log in to the Choreo Connect Environment in apictl

You can use the following command to log in to the above Choreo Connect cluster (in other words log in to the Choreo Connect adapter). When you log in, an access token will be retrieved from Choreo Connect and saved in apictl.

apictl mg login dev -k

or

apictl mg login dev -u admin -p admin -k

Step 5 - Deploy the API

Now let's deploy the API to Choreo Connect by executing the following command. 

apictl mg deploy api -f <path_to_the_API_project_just_created>/petstore -e dev -k

Step 6 - Invoke the API

After the APIs are exposed via Choreo Connect, you can invoke an API with a valid access token.

Let's use the following command to generate a JWT to access the API, and set it to the variable TOKEN. 

TOKEN=$(curl -X POST "https://localhost:9095/testkey" -d "scope=read:pets" -H "Authorization: Basic YWRtaW46YWRtaW4=" -k -v)
Execute the following cURL command to Invoke the API using the access token.

curl -X GET "https://<CHOREO-CONNECT_ROUTER_HOST>:<CHOREO-CONNECT_ROUTER_PORT>/<API-context>/<API-resource>" -H "accept:application/xml" -H "Authorization:Bearer $TOKEN" -k

curl -X GET "https://localhost:9095/v2/pet/findByStatus?status=available" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k

Info

Refer to the following content to learn more,