Call APIs through an 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.

Important

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

Complete the following steps to bind an HTTPS domain name to an API group and upload an SSL certificate.

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 target API group. In the Basic Information section, find the public second-level domain name.
Log on to the DNS console. Choose Public DNS > Authoritative DNS Resolution. Click the Authoritative Domain Names tab, and then click the domain name to open the DNS Settings tab.
On the DNS Settings tab, click Add DNS Record. Set Record Type to CNAME, Hostname to the domain name prefix, and Record Value to the public second-level domain name. 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 target API group. In the Basic Information section, find the internal VPC domain name.
Log on to the DNS console. Click Private DNS (PrivateZone). In the upper-right corner 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.

For Domain Type, select Built-in Authoritative Acceleration Zone. This is recommended for the lowest resolution latency.

Note
For Built-in Authoritative Zone, enter the custom (internal) domain name bound to the API group. This domain name is used only for private DNS (PrivateZone) in VPCs.
Click the zone name to open the Resource Records Settings tab. Click Add Record. In the Add Record panel, set Record Type to CNAME, Hostname to the domain name prefix, and Record Value to the internal VPC domain name. Click OK.

Note

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.

Note

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

Why does domain name binding fail?

The domain name is already bound to another API group on the same instance, or a wildcard domain name conflicts with a single domain name. Unbind the conflicting domain name first.
The domain name is bound to an API group owned by a different user, or a wildcard domain name conflict exists. Complete Domain name ownership verification before binding.

Upload an SSL certificate

After you bind a domain name to an API group, you can call APIs over HTTP by default. To call APIs over HTTPS, upload an SSL certificate for the domain name. API Gateway supports two methods: automatic import from Alibaba Cloud Certificate Management Service, and manual upload of a certificate from another provider.

Generate an SSL certificate

To generate a free SSL certificate through Alibaba Cloud Certificate Management Service:

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 obtain an SSL certificate, import or upload it for the domain name bound to the API group.

Import an SSL certificate

If you purchased a certificate through Alibaba Cloud Certificate Management Service, import it for the bound domain name:

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 from a third-party provider, upload it to 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 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.