Exposing APIs via Custom Hostnames¶
Virtual hosts (VHosts) enable you to expose APIs using specific hostnames that correspond to a Gateway environment. Each Gateway environment will have a minimum of one VHost. Admin users can manage Gateways by creating, updating, and deleting Gateway environments via the Admin Portal. Each Gateway environment will contain the details of each of the VHosts, which are the custom hostnames, that are applicable to that Gateway environment. As a result, API publishers can use the VHosts to group their APIs by selecting a virtual host when deploying an API to Gateway environment(s). In addition, application developers can access APIs by using the defined access URLs of the virtual host.
Using an existing Gateway environment to expose APIs via custom hostnames¶
Follow the instructions below to use the default Gateway environment to expose APIs via custom hostnames:
Step 1 - Define the custom hostnames¶
Each Gateway environment definition contains details related to a specific Gateway. Define the VHosts, which contain the custom hostnames in the deployment.toml
file, which is the central configuration file.
-
Open to the
<APIM-HOME>/repository/conf/deployment.toml
file. -
Define the VHosts.
Let's add
us.wso2.com
andfoods.com
as the custom VHosts andfood
as the custom context.Note
- When the WSO2 API Manager server is running, the default Gateway environment and also the Gateway environments that you added via the
deployment.toml
file are displayed in the Gateway environments list page in the Admin Portal in read-only mode. - If a VHost is not defined, the default VHost details are assigned to the Gateway environment.
- It is not mandatory to specify a context for the VHost.
[[apim.gateway.environment]] name = "Default" display_name = "US Region" type = "hybrid" display_in_api_console = true description = "Gateway environment deployed in the US region." show_as_token_endpoint_url = true service_url = "https://localhost:${mgt.transport.https.port}/services/" username= "${admin.username}" password= "${admin.password}" ws_endpoint = "ws://localhost:9099" wss_endpoint = "wss://localhost:8099" http_endpoint = "http://localhost:${http.nio.port}" https_endpoint = "https://localhost:${https.nio.port}" websub_event_receiver_http_endpoint = "http://localhost:9021" websub_event_receiver_https_endpoint = "https://localhost:8021" [[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" [[apim.gateway.environment.virtual_host]] ws_endpoint = "ws://foods.com:9099" wss_endpoint = "wss://foods.com:8099" http_endpoint = "http://foods.com:8280" https_endpoint = "https://foods.com:8243" websub_event_receiver_http_endpoint = "http://foods.com:9021" websub_event_receiver_https_endpoint = "https://foods.com:8021"
- When the WSO2 API Manager server is running, the default Gateway environment and also the Gateway environments that you added via the
-
This will start WSO2 API Manager in the all-in-one mode, which includes the default Gateway as well.
Step 2 - Assign the custom hostname to an API¶
Note
Repeat this step if you wish to add multiple APIs to the API group.
-
Sign in to the API Publisher using
admin
as the username and password.https://<hostname>:9443/publisher
Example:
https://localhost:9443/publisher
-
Create a new API or skip this step if you wish to use an existing API.
Let's deploy the sample Pizzashack API by clicking Deploy Sample API (If you have not done so already).
-
Click on the API to edit its configurations.
-
Click Deployments.
-
Select the newly created Gateway environment, Virtual Host (foods.com), and a Revision.
Create a new revision if no revisions exist.
-
Click Deploy to attach the Virtual Host to the Pizzashack API.
Info
Similarly, you can assign the same Virtual Host to other APIs as well.
Step 3 - View the custom hostnames¶
Follow the instructions below to view the custom endpoint URLs of the API, which consists of the custom hostnames:
-
Sign in to the Developer Portal using
admin
as the username and password.https://<hostname>:9443/devportal
Example:
https://localhost:9443/devportal
-
Click on the specific API.
-
Click Overview.
The custom endpoint URLs of the API, which include the custom hostnames, appear.
Using a new Gateway environment to expose APIs via custom hostnames¶
Follow the instructions below to use a new custom Gateway environment to expose APIs via custom hostnames:
Step 1 - Create a Gateway environment¶
Each Gateway environment definition contains details related to a specific Gateway. You can create a Gateway environment that includes VHosts using either one of the following methods.
Option 1: Create a Gateway environment via the Admin Portal¶
-
This will start WSO2 API Manager in the all-in-one mode, which includes the default Gateway as well.
-
Sign in to the Admin Portal.
https://<hostname>:9443/admin
Example:
https://localhost:9443/admin
Let's use
admin
as your username and password to sign in. -
Add a new Gateway Environment.
-
Click Gateways, and then click Add Gateway Environment.
-
Enter a name, display name, description, and a virtual host.
The virtual hosts will define each of the custom hostnames. It is mandatory to specify a VHost when you create a Gateway environment.
Environment Display Name Description Virtual Host us-region US Region Gateway environment deployed in the US region. us.wso2.com -
Optionally, click Advanced Settings to add a HTTP(S) context and custom ports.
Note
You can change the ports of each protocol of the Virtual Host and add an optional HTTP(s) context.
Let's add
gateway
as the HTTP(S) context for the Virtual Hostus.wso2.com
.Add another virtual host
foods.com
by clicking New VHost and click Save to save the environment.
-
Option 2:Create a Gateway environment using the configuration file¶
Follow the instructions below to use the deployment.toml
file, which is the central configuration file, to configure a Gateway environment that consists of virtual hosts:
-
Open to the
<APIM-HOME>/repository/conf/deployment.toml
file. -
Create a Gateway environment.
Create a Gateway environment with the following Gateway configurations, which include
us.wso2.com
andfoods.com
as the custom VHosts andfood
as the custom context.Note
- When the WSO2 API Manager server is running, the Gateway environments, which you added via the
deployment.toml
file, are displayed in the Gateway environments list page in the Admin Portal in read-only mode. - Therefore, ensure to add the VHosts that correspond to the Gateway at the time of adding the Gateway environment itself.
- If a VHost is not defined, the default VHost details are assigned to the Gateway environment.
- It is not mandatory to specify a context for the VHost.
[[apim.gateway.environment]] name = "us-region" display_name = "US Region" type = "hybrid" display_in_api_console = true description = "Gateway environment deployed in the US region." show_as_token_endpoint_url = true service_url = "https://localhost:${mgt.transport.https.port}/services/" username= "${admin.username}" password= "${admin.password}" ws_endpoint = "ws://localhost:9099" wss_endpoint = "wss://localhost:8099" http_endpoint = "http://localhost:${http.nio.port}" https_endpoint = "https://localhost:${https.nio.port}" websub_event_receiver_http_endpoint = "http://localhost:9021" websub_event_receiver_https_endpoint = "https://localhost:8021" [[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" [[apim.gateway.environment.virtual_host]] ws_endpoint = "ws://foods.com:9099" wss_endpoint = "wss://foods.com:8099" http_endpoint = "http://foods.com:8280" https_endpoint = "https://foods.com:8243" websub_event_receiver_http_endpoint = "http://foods.com:9021" websub_event_receiver_https_endpoint = "https://foods.com:8021"
- When the WSO2 API Manager server is running, the Gateway environments, which you added via the
-
This will start WSO2 API Manager in the all-in-one mode, which includes the default Gateway as well.
Step 2 - Start the second Gateway¶
Extract WSO2 API Manager to a new directory. Let's refer to this directory as APIM-HOME-2
.
-
Open the
<APIM-HOME-2>/repository/conf/deployment.toml
file. -
Set the port offset in the
server
section. -
Assign the Gateway environment label
us-region
, which is the name of the Gateway environment that you previously created. -
Update the Traffic Manager configurations of the second server to connect to the Traffic Manager deployed with the first server.
[apim.throttling] username = "$ref{super_admin.username}" password = "$ref{super_admin.password}" service_url = "https://localhost:9443/services/" throttle_decision_endpoints = ["tcp://localhost:5672","tcp://localhost:5672"] [[apim.throttling.url_group]] traffic_manager_urls = ["tcp://localhost:9611"] traffic_manager_auth_urls = ["ssl://localhost:9711"]
-
Save and close the
<APIM-HOME-2>/repository/conf/deployment.toml
file.
Step 3 - Assign the custom hostname to an API¶
Note
Repeat this step if you wish to add multiple APIs to the API group.
-
Sign in to the API Publisher using
admin
as the username and password.https://<hostname>:9443/publisher
Example:
https://localhost:9443/publisher
-
Create a new API or skip this step if you wish to use an existing API.
Let's deploy the sample Pizzashack API by clicking Deploy Sample API (If you have not done so already).
-
Click on the API to edit its configurations.
-
Click Deployments.
-
Select the newly created Gateway environment, Virtual Host (foods.com), and a Revision.
Create a new revision if no revisions exist.
-
Click Deploy to attach the Virtual Host to the Pizzashack API.
Info
Similarly, you can assign the same Virtual Host to other APIs as well.
Step 4 - View the custom hostnames¶
Follow the instructions below to view the custom endpoint URLs of the API, which consists of the custom hostnames:
-
Sign in to the Developer Portal using
admin
as the username and password.https://<hostname>:9443/devportal
Example:
https://localhost:9443/devportal
-
Click on the specific API.
-
Click Overview.
The custom endpoint URLs of the API, which include the custom hostnames, appear.