All Products
Search
Document Center

API Gateway:Bind a custom domain name to allow API calls

Last Updated:Dec 27, 2023

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 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. No limit is imposed on API calls that are initiated 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.

Note

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:

  1. Add a CNAME record for your domain name to the public second-level domain that is provided by API Gateway.

  2. 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.

Important
  • 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.

    • If the groups reside on different instances, your caller must configure Domain Name System (DNS) settings to specify 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:

  1. 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.

  2. 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

  1. 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.

  2. Go to the PrivateZone page. Click Add Zone. In the Add Zone dialog box, configure the Zone Name parameter.

Note

You must enter a custom domain name that is bound to the API group in the Zone Name field. This domain name, which must be a private domain name, is the domain name that you want to resolve in the VPC.

添加zone

3. On the Hosted Zones tab, click the name of the zone that you added in the Zone Name column. On the Resolution Settings tab of the Resolution Settings page for the zone, click Add Record. In the Add Record dialog box, set Record Type to CNAME, enter the prefix of your domain name in Resource Records, and then enter the domain name of the VPC type that you obtained in Step 1. Then, click OK. The following figure shows the configuration.

PrivateZone解析

4. Go to the PriviteZone page. Find the zone that you added and click Bind VPC in the Actions column. In the Bind VPC panel, select a region in the Regions section, select one or more VPCs in the region, and then add the VPCs to the Bound VPCs section. Click Confirm.

关联VPC

Note

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 PrivateZone.

2.2 Bind an independent domain name

1. Log on to the API Gateway console. In the left-side navigation pane, choose Open API > 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.

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.

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-44DDC1A6B20D
Important

If 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:

  1. In the Alibaba Cloud DNS console, use a CNAME record to resolve *.abc.com to the public second-level domain name.

  2. On the API Groups page in the API Gateway console, bind *.abc.com to the API group.

  3. 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.

Important

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.

  1. 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.

  2. 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 transmitted 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 Set HTTPS default domain name (dedicated instance only) section on the Group Details page.

Important

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.