Exposing APIs With Custom Hostnames in Choreo Connect Using WSO2 API Manager¶
You can expose APIs with custom hostnames 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 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 VHostus.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 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://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
Choreo Connect as a Standalone Gateway¶
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.
# 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.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 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://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