Exposing APIs With Custom Hostnames in Choreo Connect Using MWARE ESB

You can expose APIs with custom hostnames in the following ways depending on the Choreo Connect mode you have chosen.

Mode Method
Choreo Connect with MWARE ESB as a Control Plane Via MWARE ESB Publisher Portal
Choreo Connect as a Standalone Gateway Via apictl for Standalone Mode

Via MWARE ESB Publisher Portal

Follow the instructions below to use Choreo Connect with MWARE ESB as the Control Plane to expose APIs with custom hostnames via the Publisher Portal in MWARE ESB:

Info

Before you begin

This guide assumes that you already have a Choreo Connect instance that is up and running. If not, checkout the Quick Start 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 - Define Virtual Hosts

Let's define virtual hosts (VHosts) in ESB server instance by editing the deployment.toml.

Info

Refer Define Custom Hostnames for more information.

  1. Open <APIM-HOME>/repository/conf/deployment.toml file.
  2. Add the following configuration under the Default [[apim.gateway.environment]] to define the VHost us.wso2.com. 
    [[apim.gateway.environment.virtual_host]]
ws_endpoint = "ws://us.wso2.com:9099"
wss_endpoint = "wss://us.wso2.com:8099"
http_endpoint = "http://us.wso2.com/gateway"
https_endpoint = "https://us.wso2.com/gateway"
websub_event_receiver_http_endpoint = "http://us.wso2.com:9021"
websub_event_receiver_https_endpoint = "https://us.wso2.com:8021"

Step 2 - Configure Choreo Connect with ESB

Refer to documentation on how to configure Choreo Connect with ESB.

Step 3 - Create an API in ESB

Follow the steps here.

Step 4 - Deploy the API in ESB

The guide here will explain how you can easily deploy the API you just created. When deploying the API, select the Virtual Host you defined earlier (i.e. us.wso2.com).

You have successfully deployed the API to Choreo Connect with the VHost us.wso2.com.

To invoke the API, skip to the steps here.

Step 5 - Invoke the API

First we need to add the host entry to /etc/hosts file in order to access the ESB publisher and Developer Portal. Add the following entry to /etc/hosts file

127.0.0.1   us.wso2.com

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 JWT.

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

Note

You can also use header to specify the VHost to invoke the API. 

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

Via apictl for Standalone Mode

Follow the instructions below to use Choreo Connect as a Standalone Gateway to expose APIs with custom hostnames via ESB 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 Quick Start 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 - Define Virtual Hosts

Navigate to the deployment_environments.yaml file and define the virtual hosts as shown below.

type: deployment_environments
version: v4.2.0
data:
 -
   displayOnDevportal: true
   deploymentEnvironment: Default
   deploymentVhost: us.wso2.com

Info

When configuring multiple Choreo Connect Gateway environments, you have to configure the default VHost of the particular environment.

# default vhosts mapping for standalone mode
[[adapter.vhostMapping]]
  environment = <ENVIRONMENT_NAME>
  vhost = <DEFAULT_VHOST_OF_ENVIRONMENT>
# default vhosts mapping for standalone mode
[[adapter.vhostMapping]]
  environment = "Default"
  vhost = "localhost"
[[adapter.vhostMapping]]
  environment = "sg-region"
  vhost = "sg.wso2.com"

If the VHost is not declared in the API project, the API is deployed with the default VHost of the environment. For exammple, an API project with following deployment_environments.yaml will be deployed to the following. - Environment: Default - Vhost: us.wso2.com - Environment: sg-region - Vhost: sg.wso2.com - Environment: uk-region - API is not deployed to this environment becuase it is not configured in [[adapter.vhostMapping]].

type: deployment_environments
version: v4.2.0
data:
 -
   displayOnDevportal: true
   deploymentEnvironment: Default
   deploymentVhost: us.wso2.com
 -
   displayOnDevportal: true
   deploymentEnvironment: sg-region
 -
   displayOnDevportal: true
   deploymentEnvironment: uk-region

Step 2 - Deploy the API

Follow the all steps up to Deploy API in the Deploy an API via apictl documentation.

Let's invoke the API.

Step 3 - Invoke the API

First we need to add the host entry to /etc/hosts file in order to access the ESB publisher and Developer Portal.

Add the following entry to /etc/hosts file

127.0.0.1   us.wso2.com

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 JWT.

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

Note

You can also use header to specify the VHost to invoke the API. 

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

Top