When API Gateway receives an API request, it locates a unique API group based on the domain name to which the request is sent and locates a unique API in the API group based on the path and HTTP method of the request. You can bind your HTTPS domain name to an API group in the API Gateway console and upload an SSL certificate for the domain name. This way, you can call APIs in the API group through the HTTPS domain name.
Usage notes
Independent domain names that you want to bind to API groups must meet the following requirements:
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 number in the Alibaba Cloud ICP Filing system for the domain name, or add Alibaba Cloud as a service provider to the Internet content provider (ICP) filing information of the domain name.
Before you bind an independent domain name to an API group, you must add a CNAME record to map the independent domain name to the second-level domain name of the API group.
The independent domain name that you want to bind has not been bound to an API group hosted on API Gateway by other users. If the independent domain name has been bound by other users, it must be verified when you attempt to bind it. If you need to call the APIs in the API group over HTTPS, you must import or upload an SSL certificate for the independent domain name.
By default, API Gateway provides a public second-level domain name for each API group. When a client uses the public second-level domain name to initiate API calls, the number of daily API calls that the client can make is limited. The limit is 100 API calls in the China (Hong Kong) region and regions outside the Chinese mainland, and the limit is 1,000 API calls in regions inside the Chinese mainland. If you want to publish APIs to a production environment, you must bind an independent domain name to the API group to which the APIs belong. The number of API calls is not limited for independent domain names.
Procedure
The following steps demonstrate how to bind an HTTPS domain name to an API group in the API Gateway console and upload an SSL certificate for the domain name.
Domain name resolution: Add a CNAME record or TXT record to map your public or internal independent 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 Alibaba Cloud DNS (DNS) to map your public domain name to the public second-level domain name provided by API Gateway for the API group. For more information, see Public domain name resolution.
Internal domain name resolution: Use Alibaba Cloud DNS to map your internal domain name to the internal second-level domain name provided by API Gateway for 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 independent domain name to the API group. For more information, see Domain name binding.
Upload an SSL certificate: Configure an SSL certificate for the domain name so that you can use the domain name to call APIs over HTTPS. For more information, see Upload an SSL certificate.
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 private zone, the private zone record overrides the public DNS record.
In VPCs, the public DNS record of the private zone is not affected. You can add DNS records for your private zones to prevent private 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 to be bound 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
Enter 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.
Upload an SSL certificate
After a domain name is bound to an API group, you can use the domain name to call all APIs in the API group over HTTP. If you want to call APIs over HTTPS, you must upload an SSL certificate for the domain name. API Gateway provides the following methods for you to upload an SSL certificate: 1. API Gateway automatically imports an SSL certificate from the Alibaba Cloud Certificate Management Service. 2. API Gateway allows you to manually upload the SSL certificate that you obtained from other certificate service providers.
Generate an SSL certificate
To generate a free SSL certificate by using the Alibaba Cloud Certificate Management Service, perform the following steps:
Log on to the Alibaba Cloud SSL Certificates console.
On the certificate buy page, purchase the certificate and bind it to the domain name. For more information, see Get started with SSL Certificates Service. After you apply for an SSL certificate, go to the Group Details page of the API group in the API Gateway console.
Import or upload an SSL certificate
After you purchase or prepare an SSL certificate, import or upload the certificate for the domain name that you bound to the API group in the API Gateway console. The following sections describe the procedure for importing and uploading an SSL certificate.
Import an SSL certificate
If you purchase a certificate by using the Alibaba Cloud Certificate Management Service, perform the following steps to import the certificate for the domain name that you bound to the API group hosted on API Gateway:
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 desired API group to go to the Group Details page. In the Independent Domains section, you can view domain names bound to the API group. Find the domain name for which you want to import the SSL certificate and click Select Certificate in the SSL Certificate column.
In the Select Certificate dialog box, click Search for Certificate. Then, select the required certificate from the search results and click Synchronize Certificate.
Upload an SSL certificate
If your SSL certificate is not purchased from Alibaba Cloud, you can upload your certificate to API Gateway. Perform the following steps to upload an SSL certificate:
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 desired API group to go to the Group Details page. In the Independent Domains section, you can view domain names bound to the API group. Find the domain name for which you want to import the SSL certificate and click Select Certificate in the SSL Certificate column.
In the Select Certificate dialog box, click Add Certificate.
In the Create Certificate dialog box, enter and upload the certificate content as prompted, and then click Confirm.
After the certificate is uploaded, go to the Group Details page. You can find that the Select Certificate hyperlink of the domain name in the Independent Domains section is changed to Update Certificate. After the certificate is uploaded, you can use the domain name to call APIs over HTTPS.