HTTPDNS:Single domain name resolution

API access

HTTPDNS offers domain name resolution services via HTTP interfaces, utilizing direct IP connections. Refer to How to obtain the resolution service endpoint for acquiring the most current service endpoint.

For illustration, the service IP 203.107.XXX.XXX is used to demonstrate accessing the HTTPDNS service.

Request Method: Use HTTP GET or HTTPS GET (pricing varies between these methods; for details, 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, retrievable from the HTTPDNS console.

URL Parameter Description:

This interface allows you to resolve only one domain name per request.

Sample Requests:

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

• Example 2 (specified source IP): 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 support): http://[2401:b180:2000:XXXX:XXXX]/100000/d?host=www.aliyun.com&ip=219.242.XXX.XXX&query=4,6

API responses

• Successful Requests

  A successful request returns an HTTP status code of 200, with the response in 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
  }

  Parameter descriptions in the response:

  Name	Description
  host	The domain name that you want to resolve.
  ips	The list of resolved IPv4 addresses. The list may include 0, 1, or more IP addresses. This parameter is returned only when the value of query is 4.
  ipsv6	The list of resolved IPv6 addresses. The list may include 0, 1, or more IP addresses. This parameter is returned only when the value of query is 6.
  ttl	The time to live (TTL) of the resolved IP addresses.
  origin_ttl	The original TTL of the domain name, which is the TTL value configured on the authoritative DNS. 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.

  An empty ips field indicates no IP address was found for the domain name, which could be due to the domain not being added in the HTTPDNS console, unregistered domain names, or unconfigured IP addresses.

  • The domain name has not been added to the HTTPDNS console. Please add it through the console.

  • The IP addresses are missing, the domain name is unregistered, or an IP address has not been configured.

  Here's an example of a response with an empty ips field:

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

  The response includes a TTL value. To minimize frequent domain resolutions, cache the resolved IP addresses according to the TTL. Use the cached IPs until the TTL expires, after which you should update them by querying the HTTPDNS service.

• Failed Requests

  Failed requests return an HTTP status code of 4xx or 5xx, along with an error code. The response is in JSON format.

  Here's an example of a failed response:

  {
    "code": "MissingArgument"
  }

  Error codes are listed in the following table:

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

Error handling

Implement fault-tolerant logic to handle exceptions when using HTTPDNS for business, including asynchronous requests, retries, and fallbacks.

• Asynchronous Requests

  Use an asynchronous request strategy to avoid significant latency during resolution that could impact your business, particularly in abnormal network conditions or if HTTPDNS IP addresses are inaccessible. Synchronous access requires waiting for a network timeout before a failure is reported, which can degrade user experience.

  Asynchronous request strategy: Use a valid TTL IP address from the cache if available. If not, downgrade to native LocalDNS resolution while asynchronously initiating an HTTPDNS request to update the cache, ensuring future resolutions are cache hits.

• Retries

  Retry the request to the HTTPDNS server if the initial attempt fails without an HTTP response, as these failures are often due to transient network issues.

  Network issues are the common cause of such failures, and they can often be resolved by retrying.

• Fallbacks

  Should the HTTPDNS service fail to retrieve the IP address associated with a domain name, you must fallback to standard DNS resolution and resolve the domain name via LocalDNS.

  If an HTTPDNS request fails to retrieve an IP address, this typically occurs because the domain name has not been added to the console or the domain name does not exist. In any case, should HTTPDNS be unable to resolve an IP address, you must fallback to traditional DNS resolution as a backup strategy to guarantee the proper functioning of business requests.

Precautions

1. HTTP Request Header Host Field Settings

   The server uses the HOST field value in the HTTP request header to determine the domain name of the request.

   After implementing HTTPDNS, you may need to replace the HOST field value in the HTTP request URL with the resolved IP address. This can cause server resolution errors, as the server expects a domain name, not an IP address.

   Manually set the HOST field value in the HTTP request to address this. When a site is protected by Alibaba Cloud Web Application Firewall (WAF), specify the original domain name in the Host field. Here's an example using HttpURLConnection:

   // For example, if you want to access http://www.example.com/ and the resolved IP address of www.example.com is 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 original 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 Field

   Some network libraries automatically manage cookies. When using HTTPDNS, these libraries may use the IP address from the URL instead of the HOST field for cookie management, leading to issues. Disable automatic cookie management, which is typically off by default.

3. Use Under HTTPS Domain

   HTTPS protocol checks for a match between the domain name and the certificate. Using an IP address for requests can cause exceptions due to this check. To resolve:

   1. Avoid using HTTPDNS with the HTTPS protocol.

   2. Modify client certificate verification logic. For guidance, refer to:

      1. Android HTTPS (including SNI) business scenario: IP direct connection solution

      2. Use HTTPDNS in iOS HTTPS scenarios.

4. Use in Proxy Scenarios

   Using an HTTP proxy requires an absolute URL in the request line. When HTTPDNS is enabled and IP addresses are used in URLs, the proxy may pass the IP as the Host information, causing the destination server to fail processing the request. To solve this:

   1. Use native DNS resolution.

   2. Adjust server configuration to verify based on a proprietary header field, similar to the WAP gateway. For example:

   The mobile WAP gateway uses the X-Online-Host field to address this. Example:

   Target URL: http://www.example.com/product/oss/
   IP address to which www.example.com is resolved by using HTTPDNS: 192.168.XX.XX
   Proxy: 10.0.XX.XX:XX
   Your HTTP request header:
   
   GET http://192.168.XX.XX/product/oss/ HTTP/1.1     # The HTTP request header initiated by the proxy. The request line is an absolute path
   Host: www.example.com                         # This header is ignored by the proxy gateway. The proxy gateway uses the Host information in the absolute path of the request line as the host of the origin. The IP address of the host is 192.168.XX.XX
   X-Online-Host: www.example.com                # This header is a proprietary header added by the mobile gateway to pass the actual Host. The origin server needs to be configured to recognize this proprietary header to obtain the actual Host information

   Alternatively, set the X-Online-Host request header using the setRequestProperty method.

   Note

   In most cases, it's advisable to check for a network proxy on the device and avoid using HTTPDNS for domain name resolution in proxy mode.

5. Authentication Access: For more information, see implement authentication access.