HTTPDNS:Resolve a domain name

API access

HTTPDNS resolves domain names through an HTTP API accessed by IP address. To get the nearest service address, call the Obtain an address of HTTPDNS API.

The following examples use 203.107.XXX.XXX as the service IP address.

Request method: HTTP GET or HTTPS GET, priced differently (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 from the HTTPDNS console.

URL parameters:

HTTPDNS resolves one domain name per request.

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

  A successful request returns HTTP 200 with a JSON response. Example:

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

  Response parameters:

  Name	Description
  host	Resolved domain name.
  ips	Resolved IPv4 addresses. Returned only when query includes 4. May contain zero or more addresses.
  ipsv6	Resolved IPv6 addresses. Returned only when query includes 6. May contain zero or more addresses.
  ttl	TTL of the resolved IP addresses.
  origin_ttl	Original TTL configured on the authoritative DNS server. Important This value may not be returned if the backend cannot retrieve the original TTL.

  A successful response may return an empty ips list. Common causes:

  • The domain name is not added in the HTTPDNS console. Add it to enable resolution.

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

  Example response with an empty ips list:

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

  Cache resolved IP addresses until the TTL expires, then query HTTPDNS for updated results.

• Failed request

  A failed request returns HTTP 4xx or 5xx with a JSON error code.

  Example:

  {
    "code": "MissingArgument"
  }

  Error codes:

  Error code	HTTP status code	Description
  MissingArgument	400	Required parameters are missing.
  InvalidHost	400	Invalid domain name format.
  TooManyHosts	400	Multiple domain names are passed.
  SdnsNotSupported	400	SDNS is unavailable in the requested region outside the Chinese mainland.
  InvalidAccount	403	Invalid or nonexistent account.
  MethodNotAllowed	405	Unsupported HTTP method.
  InternalError	500	Internal server error.

Error handling

Implement error handling for HTTPDNS with asynchronous requests, retries, and degradation.

• Asynchronous request

  Use asynchronous requests to prevent latency impacts, especially when network conditions are poor or HTTPDNS addresses are unavailable. Synchronous requests block until network timeout, which degrades user experience.

  Implementation: Use cached IP addresses if the TTL has not expired. If all TTLs have expired, fall back to local DNS and asynchronously refresh the HTTPDNS cache in a separate thread.

• Retry

  Retry the request if the HTTPDNS server fails to respond.

  Most failures are caused by transient network issues.

• Degradation

  If HTTPDNS cannot resolve a domain name, fall back to local DNS using a degraded resolution method.

  This may happen when the domain name is not configured in the console or does not exist. Degradation ensures service availability.

Usage notes

1. Settings for the HOST header in the HTTP request

   The server uses the Host header to identify the target domain.

   When you replace the URL host with an HTTPDNS-resolved IP address, the network library sets the Host header to the IP address, causing server-side resolution errors.

   Set the Host header explicitly to the domain name. If your website is protected by Alibaba Cloud Web Application Firewall (WAF), you must set the HOST header to the domain name. HttpURLConnection 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

   Some network libraries manage cookies automatically using the URL IP address instead of the Host header for domain identification, causing cookie issues. Disable automatic cookie management if enabled (disabled by default).

3. Use an HTTPS domain name

   HTTPS certificate verification fails when the request URL contains an IP address instead of a domain name. Solutions:

   1. Disable HTTPDNS for HTTPS requests (recommended).

   2. Modify the client certificate verification logic:

      1. Best practices for HTTPDNS and HttpURLConnection on Android

      2. Use HTTPDNS in a native iOS scenario.

4. Use a proxy

   When using an HTTP proxy with HTTPDNS, the proxy forwards the IP address as the Host to the destination server, which cannot resolve the actual domain. Solutions:

   1. Use native DNS resolution to avoid this issue.

   2. Add a custom header field for server-side verification. Common for WAP gateways.

   Mobile WAP gateways use the X-Online-Host header to transmit the real host. 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.

   Use the setRequestProperty method to set the X-Online-Host header.

   Note

   Check whether a network proxy is active on the device. Avoid using HTTPDNS in proxy mode.

5. Authenticated access: Implement authentication access.