HTTPDNS:Resolve a domain name

API access

HTTPDNS provides the domain name resolution service using the HTTP API. You can directly access HTTPDNS through IP addresses. For more information about how to obtain the nearest address of HTTPDNS in real time, see Obtain an address of HTTPDNS.

This section uses the service IP address 203.107.XXX.XXX as an example to show how to access the HTTPDNS service.

Request method: HTTP GET or HTTPS GET. The prices of the two request methods are different. For more information, see Billing.

HTTP service URL: http://203.107.XXX.XXX/{account_id}/d

HTTPS service URL: https://203.107.XXX.XXX/{account_id}/d

Replace {account_id} with your HTTPDNS Account ID. You can find the ID in the HTTPDNS console.

The following table describes the parameters in the URL.

When you access HTTPDNS, you can resolve only one domain name at a time.

Sample request:

• Example 1 (Default source): http://203.107.XXX.XXX/100000/d?host=www.aliyun.com

• Example 2 (Specified source): http://203.107.XXX.XXX/100000/d?host=www.aliyun.com&ip=42.120.XX.XXX

• Example 3 (Specified resolution type): http://203.107.XXX.XXX/100000/d?host=www.aliyun.com&ip=219.242.XXX.XXX&query=4,6

• Example 4 (IPv6 ): http://[2401:b180:2000:XXXX:XXXX]/100000/d?host=www.aliyun.com&ip=219.242.XXX.XXX&query=4,6

API responses

• Successful request

  If a request is successful, the HTTP status code 200 is returned. The response is in the JSON format. Example:

  {
    "host":"www.aliyun.com",
    "ips":[
      "192.168.XX.234"
    ],
    "ipsv6":[
      "2400:3200:1300:0:0:0:XX:XX"
    ],
    "ttl":57,
    "origin_ttl":120
  }

  The following table describes the response parameters.

  Name	Description
  host	The domain name that is resolved.
  ips	The list of returned IPv4 addresses. The list may include 0, 1, or multiple IP addresses. This parameter is returned only when the value of query is 4.
  ipsv6	The list of returned IPv6 addresses. The list may include 0, 1, or multiple IP addresses. This parameter is returned only when the value of query is 6.
  ttl	The time to live (TTL) of the returned IP addresses.
  origin_ttl	The original TTL of the domain name. The TTL value of the domain name is configured on an authoritative Domain Name System (DNS) server. Important The TTL value of the domain name may fail to be obtained because the service backend resolves different domain names in different ways. In this case, this parameter is not returned.

  If a request is successful, the ips field in the response may be an empty list. This indicates that no IP address was obtained for the domain name. This can occur for two main reasons:

  • The domain name is not added in the HTTPDNS console. We recommend that you go to the HTTPDNS console to add the domain name.

  • No IP address exists for the domain name, the domain name is not registered, or no IP address is configured.

  The following is an example of a response with an empty ips field:

  {
    "host":"www.aliyun.com",
    "ips":[],
    "ttl":300
  }

  To avoid frequent domain resolution, follow the TTL value that is returned in the result. Before the TTL expires, use the cached IP addresses. After the TTL expires, access HTTPDNS to obtain the latest resolution result.

• Failed request

  If a request fails, the HTTP status code 4xx or 5xx is returned, and an error code is also returned. The response is displayed in the JSON format.

  Example:

  {
    "code": "MissingArgument"
  }

  The following table describes the error codes.

  Error code	HTTP status code	Description
  MissingArgument	400	One or more required parameters are missing.
  InvalidHost	400	The format of the domain name is invalid.
  TooManyHosts	400	Multiple domain names are passed.
  SdnsNotSupported	400	You are in a country or region outside the Chinese mainland where the Software-Defined Name System (SDNS) service is not available.
  InvalidAccount	403	The account is invalid or does not exist.
  MethodNotAllowed	405	The HTTP method is not supported.
  InternalError	500	An internal error occurred on the server.

Error handling

When you use HTTPDNS, you must implement an error-compatible logic in case of exceptions. Using the logic, you can perform asynchronous requests, retries, or degradation.

• Asynchronous request

  To prevent business impacts caused by high latency, make asynchronous requests to access HTTPDNS. This is especially helpful when the network environment is abnormal or the IP addresses of HTTPDNS are unavailable. If you make synchronous requests to access HTTPDNS, you must wait for the network timeout before resolution failures are returned. This timeout period may significantly affect user experience.

  Implementation: If an IP address for which the TTL does not expire is available, use the IP address. If the TTL of all IP addresses expires, degrade the request to use native local DNS resolution and start another thread to asynchronously initiate an HTTPDNS resolution request. This way, the cache is updated and the TTL can be hit when the domain name is subsequently resolved.

• Retry

  When you use HTTPDNS to resolve a domain name, if the request to the HTTPDNS server fails or no HTTP request is returned, you can try again.

  In most cases, this failure is caused by network issues and can be solved after retries.

• Degradation

  If no IP addresses that a domain name points to can be obtained using HTTPDNS, you must use a degraded resolution method. In this case, use local DNS to resolve the domain name.

  The request to HTTPDNS does not return an IP address because the domain name is not added to the console or the domain name does not exist. Use a degraded resolution method to ensure service availability.

Usage notes

1. Settings for the HOST header in the HTTP request

   Over the standard HTTP protocol, the server resolves the value of the Host header in an HTTP request as the domain name information.

   When you use HTTPDNS, you may need to replace the host parameter in the HTTP URL with the IP address obtained by HTTPDNS resolution. In this case, the standard network library assigns the IP address to the HOST header in the HTTP request, which causes resolution errors on the server because the server recognizes your domain name instead of the IP address.

   To address this issue, you can specify the value of the HOST header in the HTTP request. If your website is protected by Alibaba Cloud Web Application Firewall (WAF), you must set the HOST header to the domain name. The following code uses HttpURLConnection as an example.

   // For example, the domain name www.example.com that you want to visit is resolved to the IP address 192.168.XX.XX. 
   // In most cases, if you want to use the IP address for access, you must set the HOST header in the HTTP request to the domain name. 
   String fullPath ="http://192.168.XX.XX/";
   String host ="www.example.com";
   URL url =new URL(fullPath);
   HttpURLConnection conn =(HttpURLConnection) url.openConnection();
   // Set the Host header in the HTTP request to www.example.com.
   conn.setRequestProperty("Host", host);

2. Cookie header

   Specific network libraries support automatic storage management of cookies. When you use HTTPDNS to make requests, these network libraries use the IP address information in your URL instead of the HOST header in the HTTP request as the domain name information for cookie storage management. This may cause issues in the management and use of cookies. Therefore, you must disable the automatic cookie management feature. By default, this feature is disabled.

3. Use an HTTPS domain name

   When you use the HTTPS protocol, the system checks whether your domain name matches the certificate. If you use an IP address to make requests, the network libraries check the IP address. This leads to exceptions. You can use the following methods to solve the issue:

   1. Disable HTTPDNS. We recommend that you use this method.

   2. Modify the logic for verifying the client certificate. For more information, see

      1. Best practices for HTTPDNS and HttpURLConnection on Android

      2. Use HTTPDNS in a native iOS scenario.

4. Use a proxy

   If you use an intermediate HTTP proxy, the URL of an absolute path is used in the request line of a request initiated by the client. When you enable HTTPDNS and use an IP address for access, the proxy identifies your IP address information and passes it to the destination server as the actual Host information. In this case, the destination server is unable to process such an HTTP request that does not have actual HOST information. You can use the following methods to solve the issue:

   1. Use native DNS resolution to avoid this issue.

   2. Modify the server configuration, for example, add another header field. In this case, the server performs verification based on the header field that you add. This method is commonly used for WAP gateways.

   Mobile WAP gateways use the X-Online-Host private protocol field to resolve this problem. The following is an example:

   Destination URL: http://www.example.com/product/oss/
   IP address to which www.example.com is resolved using HTTPDNS: 192.168.XX.XX
   Proxy: 10.0.XX.XX:XX
   HTTP request headers:
   
   GET http://192.168.XX.XX/product/oss/ HTTP/1.1     # The HTTP request header initiated by the proxy. The request line contains an absolute path.
   Host: www.example.com                         # This header is ignored by the proxy gateway. The proxy gateway uses the Host information in the request line as the host of the origin, which is 192.168.XX.XX.
   X-Online-Host: www.example.com                # This header is a private header added by the mobile gateway to transmit the real Host information. The header must be configured for the origin. This way, the origin can recognize the header to obtain the real Host information.

   You can also use the setRequestProperty method to set the X-Online-Host request header field.

   Note

   In most scenarios, we recommend that you check whether the network proxy is enabled for the current device. Do not use HTTPDNS for domain name resolution in proxy mode.

5. For information about an authenticated mode for access, see Implement authentication access.