This topic describes how to bind your domain name to an API group that is hosted on API Gateway. This way, you can provide external services by allowing clients to use your domain name to call APIs in this API group.
1. Overview
1.1 How are domain names, API groups, and APIs related?
You must bind your domain name to an API group that is hosted on API Gateway to establish a mapping between the domain name and the API group.
When API Gateway receives an HTTP request from a client, API Gateway identifies to which API group and API to forward the request based on the domain name, HTTP method, and path information in the request.
By default, API Gateway provides a public second-level domain name for each API group. If a client uses the default public second-level domain name to call APIs in an API group, a limit of 100 API calls per day is imposed on the China (Hong Kong) region and other regions outside the Chinese mainland, and a limit of 1,000 API calls per day is imposed on regions inside the Chinese mainland. The response to each request that is initiated to call the public second-level domain name provided by API Gateway contains the "Content-Disposition: attachment; filename=ApiResponseForInnerDomain" information in the header. If you want to publish APIs in production environments, you must bind an independent domain name to the corresponding API group. The limit on the number of API calls that are initiated for the public second-level domain name does not take effect for independent domains.
1.2 ICP filing
If you want to bind an independent domain name to an API group in a region inside the Chinese mainland, you must apply for an ICP filing or add Alibaba Cloud as a service provider to the ICP filing information of the independent domain name. If you want to bind an independent domain to an API group in a region outside the Chinese mainland, ICP filing is not required.
If you want to bind an internal domain name to an API group, ICP filing is not required.
1.3 Ownership verification of domain names
A domain name can be bound to an API group only when the following conditions are met: the domain name is not bound to another API group that belongs to the same instance and uses the same base path as the current API group, and the domain name does not conflict with other wildcard domain names that are bound to the API group. You can use one of the following methods to verify the ownership of a domain name:
Add a CNAME record for your domain name to the public second-level domain name that is provided by API Gateway.
Add a record of the TXT type to the bound domain name. The record is named in the API group ID.Domain name format, and the record value is in the apigateway-domain-verification=Public second-level domain name format. Example:
The ID of the API group is b7eb2f79e64f4431b08bbb948ed2567e. The public second-level domain name is b7eb2f79e64f4431b08bbb948ed2567e-cn-hangzhou.alicloudapi.com. The domain name that is bound to the API group is a single domain name, such as youdomain.com, or a wildcard domain name, such as *.yourdomain. You must add a record whose record type is TXT, hostname is b7eb2f79e64f4431b08bbb948ed2567e.yourdomain.com, and record value is apigateway-domain-verification=b7eb2f79e64f4431b08bbb948ed2567e-cn-hangzhou.alicloudapi.com to the domain name.
You do not need to verify the ownership of an internal domain name that is bound to an API group.
If you bind your domain name to an API group but do not add a CNAME record for the domain name, domain name requests from clients cannot be routed to API Gateway.
If you want to bind a domain name to different API groups, take note of the following items:
If the groups reside on the same instance, their BasePath values must be different. The base path can be up to 300 bytes in length.
If the groups reside on different instances, your caller must configure Domain Name System (DNS) settings to specify to which instance to send a request on their clients.
2. Bind a single domain name
To bind your single domain name to an API group, perform the following steps:
Domain name resolution: Add a CNAME record or a TXT record for your independent domain name to the public second-level domain name that is provided by the API group.
Domain name binding: On the Group Details page in the API Gateway console, bind your independent domain name to the API group.
2.1 Add a CNAME record for your independent domain name
2.1.1 Resolution of the public second-level domain name
1. On the Group Details page in the API Gateway console, find the default second-level domain name.
2. Log on to the Alibaba Cloud DNS console. In the left-side navigation pane, click Manage DNS. On the Managed DNS page, find the domain name that you want to resolve and click the domain name in the Domain Name column to go to the DNS Settings page.
3. Click Add Record. In the Add Record panel, set Type to CNAME, Host to the prefix of the domain name, and Value to the public second-level domain name that you obtained in Step 1. Then, click Confirm.
2.1.2 Resolution of an internal domain name
On the Group Details page in the API Gateway console, find the domain name of the virtual public cloud (VPC) type that is provided for the API group.
Go to the Alibaba Cloud DNS console. In the left-side navigation pane, click Private DNS (PrivateZone). On the Built-in Authoritative Module tab, click Add New Zone. In the Add Built-in Authoritative Zone panel, specify the Built-in Authoritative Zone parameter.
For the Built-in Authoritative Zone parameter, you must enter the custom domain name that is bound to the API group.
3. Click the zone name. On the Resource Records Settings tab, click Add Record. In the Add Record panel, configure a CNAME record. In the Add Record panel, select CNAME from the Record Type drop-down list, enter the prefix of your domain name in Hostname, and then enter the domain name of the VPC type that you obtained in Step 1 in Record Value. Then, click OK. The following figure shows an example:
4. Go to the Private DNS (PrivateZone) page. Find the zone that you added and click Effective Scope Settings in the Actions column. On the Zone Settings tab, select a VPC in the Alibaba Cloud VPC field. Click OK.
On the Elastic Compute Service (ECS) instance that is deployed in the VPC associated with a private zone, the private zone record overrides the DNS record on the Internet. Take note that the DNS record on the Internet is not affected outside the VPC. We recommend that you add records for your private zone. For queries that are initiated in the VPC, an empty record in the private zone may override the DNS record on the Internet. This causes errors. For more information, see Activate Alibaba Cloud DNS PrivateZone.
2.2 Bind an independent domain name
1. Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups. On the API Groups page, find the API group to which you want to bind your independent domain name and click the name of the API group in the Group column. On the Group Details page, click Bind Domain Name in the Independent Domains section.
2. In the Bind Domain Name dialog box, enter the domain name that is resolved in the Domain Name field and click Confirm.
Domain Name: the domain name that you want to bind to the API group.
Environment: the environment that is associated with the domain name. Valid values:
TEST: You can call only the APIs in the test environment.
PRE: You can call only the APIs in the staging environment.
RELEASE: You can call only the APIs in the production environment.
Default (X-Ca-Stage): You can call all APIs in the preceding environments. When you call an API, add the X-Ca-Stage parameter to the header of your request to specify the environment in which you want to call the API.
Network Type: The Internet type allows you to call APIs only over the Internet. If you set Network Type to Internal Network, you can call APIs only over internal networks.
You do not need to verify the ownership of an internal domain name. If the domain name conflicts with a domain name that is bound to another API group that belongs to the same instance as the current API group, the current domain name fails to be bound to the API group.
After the domain name is bound to the API group, you cannot change the network type of the domain name. If the configuration is incorrect, you can delete the domain name and bind the domain name to the API group again.
2.3 Handle failures to bind domain names
Causes and solutions:
The domain name that you want to bind is bound to another API group on the current instance, or is in range conflict with another domain name that you have bound. In a range conflict, a wildcard domain name includes a single domain name. In this case, you must unbind that domain name before you can bind the current domain name.
The domain name that you want to bind is bound to an API group created by a different user, or is in range conflict with another domain name that you have bound. In a range conflict, a wildcard domain name includes a single domain name. In this case, you must follow the instructions described in the "Ownership verification of domain names" section of this topic to verify the ownership of the domain name.
2.4 Call APIs
After the binding is complete, you can use the domain name to call an API in the API group. The following example shows how to call an API by using cURL:
curl http://yourdomain.com/apipath -i
HTTP/1.1 200 OK
Date: Mon, 23 Mar 2020 08:40:01 GMT
Connection: keep-alive
Keep-Alive: timeout=25
Server: Jetty(7.2.2.v20101205)
X-Ca-Request-Id: E2B8CBAB-D6EF-4576-838F-44DDC1A6B20DIf the bound domain name is an internal domain name, you must call APIs in the VPC that is associated with the domain name.
3. Bind a wildcard domain name
API Gateway allows you to bind wildcard domain names to API groups. You can resolve a wildcard domain name to the public second-level domain name and bind the wildcard domain name to your API group in the API Gateway console. After the binding is complete, you can use the wildcard domain name to call APIs in the API group that is hosted on API Gateway.
For example, if you are the owner of the domain name abc.com and you want to resolve all subdomains, such as 1.abc.com and 2.abc.com of abc.com, to API Gateway to provide external services, you can perform the following steps:
In the Alibaba Cloud DNS console, use a CNAME record to resolve *.abc.com to the public second-level domain name.
On the API Groups page in the API Gateway console, bind *.abc.com to the API group.
After the binding is complete, the client can access APIs in the API group by using one of the subdomains of abc.com. For example, if an API in the API group can be anonymously called by using the GET method, the API can also be called by using the subdomains of *.abc.com.
Only the instances that are deployed in a VPC support wildcard domain names.
3.1 Procedure
The operations that you perform to bind a wildcard domain name are similar to the operations that you perform to bind a single domain that is described in the "Bind a single domain" section of this topic.
When you bind a wildcard domain name, you must verify the ownership of the wildcard domain name. For more information, see the "Ownership verification of domain names" section.
After a wildcard domain name is bound, you must configure a wildcard domain name template on the Group Details page. Then, you can use the wildcard domain name to call APIs.
The wildcard domain name template is used to configure domain name parameters. Variable fields in the template can be passed as parameters to the backend service.
4. Configure a default domain name
API Gateway allows you to upload an HTTPS certificate for your domain name. Then, you can use the domain name to call APIs over HTTPS. If multiple domain names are bound to an API group, and all these domain names support HTTPS-based API calls, you must configure a default domain name. This way, API Gateway can return the certificate for the default domain name when API Gateway receives an SSL handshake request from a client that does not support SNI. If no default domain name is configured, API Gateway randomly returns the certificate for a domain name. The configuration of a default domain name applies only to dedicated instances. By default, shared instances do not support the certificate for a default domain name. If a client of an earlier version that does not support SNI makes API calls over HTTPS, a certificate confusion error may occur.
You can configure a default domain name in the Default Domain Name to Support Access over HTTPS (For dedicated instances only) section on the Group Details page.
In a dedicated instance, if multiple API groups are all configured with default domain names, only the default domain name that is configured for the first API group can be loaded.