All Products
Search
Document Center

Bind a domain name to an API group

Last Updated: Feb 24, 2022

This topic describes how to bind your domain name to an API group hosted on API Gateway. This way, you can use your domain name to call APIs in the API group and provide external services.

1. Overview

1.1 Relationships between domain names and API groups and between domain names and APIs

You must bind your domain name to an API group hosted on API Gateway to establish a mapping. When API Gateway receives an HTTP request from a client, API Gateway identifies the API group to which the request belongs based on the domain name in the request, and determines a unique API in the API group based on HTTP Method and Request Path. API Gateway provides a default Internet second-level domain for each API group. A client can call the Internet second-level domain for a maximum of 1,000 times per day. By default, a response that is generated when an Internet second-level domain is called contains the "Content-Disposition: attachment; filename=ApiResponseForInnerDomain" information in the header. When you publish APIs in a production environment, you must bind an independent domain to the destination API group. The number of API calls is not limited for independent domains.

1.2 ICP filing

If you want to bind an independent domain to an API group in a region inside mainland China, you must apply for an ICP filing or access the independent domain at Alibaba Cloud ICP filing. If you want to bind an independent domain to an API group in a region outside mainland China, ICP filing is not required.

1.3 Ownership verification of domain names

If your domain name has been bound to an API group by other users, or conflicts with a wildcard domain name that has been bound, the domain name must pass ownership verification. Otherwise, the domain name cannot be bound. 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 Internet second-level domain provided by API Gateway.

  1. Add a TXT record that contains the following information for your domain name: record name in the format of API Group ID.Domain name and record value in the format of apigateway-domain-verification=Internet second-level domain. Example:

The ID of a specific API group is b7eb2f79e64f4431b08bbb948ed2567e. The Internet second-level domain that is provided for the API group 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 can add a record whose record type is TXT, record name is b7eb2f79e64f4431b08bbb948ed2567e.yourdomain.com, and record value is apigateway-domain-verification=b7eb2f79e64f4431b08bbb948ed2567e-cn-hangzhou.alicloudapi.com for the domain name.

2. Bind a single domain name

Perform the following steps to bind your single domain name to an API group:

  1. Optional. Add a CNAME record for your single domain name to the Internet second-level domain provided for a specific API group.

  1. Bind your single domain name to the API group on the Group Details page of the API Gateway console.

If the operation in Step 1 fails, you can also perform Step 2 to bind your single domain name to the API group. During the binding process, if no domain name conflict occurs, API Gateway does not check whether a CNAME record is added for your single domain name. If you bind your single domain name to an API group with no CNAME record added, a domain name request from a client cannot be routed to API Gateway.

2.1 Add a CNAME record for your single domain name

Step 1 On the Group Details page of the API Gateway console, find the Internet second-level domain provided for the destination API group.

Step 2 Log on to your DNS management platform. If you use Alibaba Cloud DNS, visit https://dns.console.aliyun.com. On the Manage DNS page of the Alibaba Cloud DNS console, click your single domain name to go to the DNS Settings page.

Step 3 Click Add Record. In the Add Record panel, set Type to CNAME, Host to test, and Value to the Internet second-level domain that you obtained in Step 1, and then click Confirm.

2.2 Bind your single domain name

Step 1 Log on to the API Gateway console. In the left-side navigation pane, choose Publish APIs > API Groups. On the Group List page, click the API group to which you want to bind your single domain name. The Group Details page appears. Step 2 In the lower-right corner of the Group Details page, click Bind Domain.

Step 3 In the Bind Domain Name dialog box, set Domain Name to test.yourdomain.com and click OK.

2.3 Troubleshooting

Causes of domain name binding failures and solutions:

  • The domain name that you want to bind has already been bound to another API group, or is in range conflict with another domain name that you have bound. The range conflict indicates that a wildcard domain name overlaps a single domain name. In this case, you must unbind the domain name, and then bind the domain name to the destination API group.

  • The domain name that you want to bind has already been bound to an API group created by a different user, or is in range conflict with another domain name that you have bound. In this case, you must follow the instructions described in the "Ownership verification of domain names" section to verify the ownership of the domain name.

2.4 Make API calls

After the binding is complete, you can use this 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

3. Wildcard domain names

3.1 Support for wildcard domain names

API Gateway allows you to bind wildcard domain names to API groups. You can resolve a wildcard domain name to API Gateway 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 hosted on API Gateway. Assume that you are the owner of the domain name abc.com. If 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, perform the following steps:

  1. On your DNS management platform, use a CNAME record to resolve *.abc.com to the Internet second-level domain of the destination API group.

  1. On the Group List page of the API Gateway console, bind *.abc.com to the destination 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.2 Bind a wildcard domain name

The process of binding a wildcard domain name is similar to that of binding a single domain name. The differences between these two processes lie in the following aspects:

  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.

  1. After a wildcard domain name is bound, you must configure the 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 to the backend service as parameters.

4. Configure a default domain name

API Gateway allows you to upload an HTTPS certificate for your domain name so that 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 it receives an SSL handshake request from a client that does not support SNI. If no default domain name is configured, API Gateway returns the certificate for a domain name randomly. 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 problem 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, as shown in the following figure.

In a dedicated instance, if multiple API groups are all configured with default domain names, only the default domain name configured for the first API group can be loaded.