Deploying a REST API in Choreo Connect

You can deploy a REST type API in Choreo Connect using either one of the following Choreo Connect modes:

Choreo Connect with WSO2 API Manager as a Control Plane

Follow the instructions below to use Choreo Connect with WSO2 API Manager as the Control Plane to deploy a REST type API via the Publisher Portal in WSO2 API Manager:

Step 1 - Configure Choreo Connect with API Manager

Step 2 - 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 3 - 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.

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 belongs to the gateway environment given in environmentLabels. These artifacts include deployed APIs, Applications, Subscriptions, Polices, 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.

Note

You might find the following content useful here onwards,

Step 4 - Invoke the API

After the APIs are exposed via Choreo Connect, you can invoke an API with a valid token (JWT or opaque 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 JWT.

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.

Choreo Connect as a Standalone Gateway

Follow the instructions below to use Choreo Connect as a Standalone Gateway to deploy a REST type API via WSO2 API Controller (apictl), which is a CLI Tool:

Info

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 Compose 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 an 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). By logging 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

Note

Refer to the following content to learn more,

Step 6 - Invoke the API

After the APIs are exposed via Choreo Connect, you can invoke an API with a valid token (JWT or opaque 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 JWT.

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.

Top