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 call APIs in the API group through your domain name.
Overview
Relationship between domain names and API groups and relationship between domain names and APIs
You must bind your domain name to an API group that is hosted on API Gateway to create a mapping between the domain name and API group.
When API Gateway receives an HTTP request from a client, API Gateway identifies the API group and API to which the request is forwarded based on the domain name, HTTP method, and path in the request.
By default, API Gateway provides a public second-level domain name for each API group. When a client uses the default public second-level domain name to call APIs in an API group, the number of daily API calls is limited. The limit is 100 API calls per day in the China (Hong Kong) region and other regions outside the Chinese mainland, and the limit is 1,000 API calls per day in regions inside the Chinese mainland. The response to each request that is initiated to call APIs through 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 a separate domain name to the corresponding API group. In this case, the number of daily API calls is not limited.
ICP filing for a domain name
If you want to bind a separate domain name to an API group in a region inside the Chinese mainland, you must apply for an Internet content provider (ICP) number or add Alibaba Cloud as a service provider to the ICP filing information of the separate domain name. No ICP filing is required for domain names hosted outside the Chinese mainland.
If you want to bind an internal domain name to an API group, ICP filing is not required.
Domain name ownership verification
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 to map your domain name to the second-level domain name assigned by the system.
Add a TXT record for the domain name that is bound to the API group. 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 isb7eb2f79e64f4431b08bbb948ed2567e-cn-hangzhou.alicloudapi.com. The domain name that is bound to the API group is a single domain name, such asyoudomain.com, or a wildcard domain name, such as*.yourdomain. You must add a TXT record whose hostname (RR) isb7eb2f79e64f4431b08bbb948ed2567e.yourdomain.comand record value isapigateway-domain-verfication=b7eb2f79e64f4431b08bbb948ed2567e-cn-hangzhou.alicloudapi.comfor 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, requests sent from clients to the domain name 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 API groups reside on the same instance, their base paths must be different. A base path can be up to 300 bytes in length.
If the API groups reside on different instances, the clients must specify the requested instance in their Alibaba Cloud DNS (DNS) settings.
Procedure
To bind a public or internal domain name to API Gateway, perform the steps in Bind a single domain name or Bind a wildcard domain name.
Domain name resolution: Add a CNAME record or TXT record to map your public or internal domain name to the public or internal second-level domain name that is provided by the API group. For more information, see Domain name resolution.
Public domain name resolution: You can use DNS to map your public domain name to the public second-level domain name of the API Gateway group. For more information, see Public domain name resolution.
Internal domain name resolution: Use DNS to map your internal domain name to the internal second-level domain name of the API group. For more information, see Internal domain name resolution.
Domain name binding: On the Group Details page of the API Gateway console, bind your domain name to the API group. For more information, see Domain name binding.
Optional. Configure the default domain name of the API group: If multiple domain names are bound to the API group and the domain names support HTTPS, you must configure the default domain name. For more information, see Configure the default domain name of the API group.
Bind a single domain name
Domain name resolution
Public domain name resolution
Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups and select a region.
On the API Groups page, click the API group that you want to manage to go to the details page. In the Basic Information section, find the public second-level domain name provided by API Gateway for the API group.
Log on to the DNS console. In the left-side navigation pane, choose Public DNS > Authoritative DNS Resolution. On the Authoritative DNS Resolution page, click the Authoritative Domain Names tab. Click the desired domain name to go to the DNS Settings tab.
On the DNS Settings tab, click Add DNS Record. In the dialog box that appears, set Record Type to CNAME, Hostname to the prefix of the domain name, and Record Value to the public second-level domain name. Then, click OK.
Internal domain name resolution
Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups and select a region.
On the API Groups page, click the API group that you want to manage to go to the details page. In the Basic Information section, find the internal virtual private cloud (VPC) domain name provided by API Gateway for the API group.
Log on to the DNS console. In the left-side navigation pane, click Private DNS (PrivateZone). In the upper-right part of the Private DNS (PrivateZone)page, click Configuration Mode. On the User Defined Zones tab, click Add New Zone.
In the Add Built-in Authoritative Zone panel, specify Built-in Authoritative Zone and Alibaba Cloud VPC, and click OK.
NoteFor the Built-in Authoritative Zone parameter, you must enter the custom (internal) domain name that is bound to the API group. The domain name is dedicated to private DNS (PrivateZone) in VPCs.
Click the name of the built-in authoritative zone to go to the Resource Records Settings tab. Click Add Record to add a CNAME record for the internal domain name. In the Add Record panel, set Record Type to CNAME, Hostname to the prefix of the domain name, and Record Value to the internal VPC domain name. Then, click OK.
On the Elastic Compute Service (ECS) instance that is deployed in the VPC associated with the built-in authoritative zone, the private zone record overrides the public DNS record. The internal domain name is resolved based on the private zone record.
In a VPC, the public DNS record of the built-in authoritative zone is not affected. The private zone record added for the built-in authoritative zone can prevent built-in authoritative zones whose DNS records are empty from overwriting the public DNS record. Otherwise, DNS resolution errors occur. For more information, see Activate Alibaba Cloud DNS PrivateZone.
Domain name binding
Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups and select a region.
On the API Groups page, click the API group that you want to bind to the domain name to go to the Group Details page. In the Independent Domains section, click Bind Domain Name.
In the Bind Domain Name dialog box, configure the following parameters and click Confirm.
Parameter
Description
Domain Name
Specify the domain name to be bound 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.
Production: 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
Internet: You can call APIs only over the Internet. 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.
FAQ about domain name binding
What do I do if the domain name fails to be bound to an API group?
The domain name that you want to bind is bound to another API group on the current instance, or its range conflicts with another domain name that you have bound. The range conflict refers to that a wildcard domain name overwrites 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 its range conflicts with another domain name that you have bound. The range conflict refers to that a wildcard domain name overwrites a single domain name. In this case, you must verify the ownership of the domain name by following the instructions in the Domain name ownership verification section before you can bind the current domain name.
Verify API calls
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 an internal domain name is bound to the API group, you must call APIs in the VPC that is associated with the domain name.
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.
How are wildcard domain names bound to API groups
Wildcard domain names are bound to API groups in a similar way as the procedure in the Bind a single domain name section. 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 DNS console, create a CNAME record to map *.abc.com to the public second-level domain name.
On the Group Details page in the API Gateway console, bind *.abc.com to the API group.
Only instances that are deployed in VPCs support wildcard domain names. After the binding is complete, the client can call APIs in the API group by using one of the subdomains of abc.com, such as 1.abc.com and 2.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.
Usage notes for wildcard domain name binding
When you bind a wildcard domain name, you must verify the ownership of the wildcard domain name. For more information, see the "Domain name ownership verification" 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 backend services.
Configure the default domain name of an API group
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, you must configure the 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 server name indication (SNI). If no default domain name is configured, API Gateway randomly returns the certificate for a domain name. The default domain name configuration 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.
On 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.