

Exposing APIs With Custom Hostnames in Choreo Connect Using WSO2 API Manager¶

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 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 use Choreo Connect with WSO2 API Manager as the Control Plane to expose APIs with custom hostnames via the Publisher Portal in WSO2 API Manager:

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 API Manager server instance by editing the deployment.toml.

Info

Refer Define Custom Hostnames for more information.

Open <APIM-HOME>/repository/conf/deployment.toml file.

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 API Manager¶

Refer to documentation on how to configure Choreo Connect with API Manager.

Step 3 - Create an API in API Manager¶

Follow the steps here.

Step 4 - Deploy the API in API Manager¶

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 API Manager 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 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 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.1.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.

Format

# default vhosts mapping for standalone mode
[[adapter.vhostMapping]]
  environment = <ENVIRONMENT_NAME>
  vhost = <DEFAULT_VHOST_OF_ENVIRONMENT>

Example

# 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.1.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 API Manager 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