HTTPDNS:Install HTTPDNS SDK for iOSResolve a domain name

API access

1. Access method

   HTTPDNS provides the domain name resolution service by using the HTTP API. You can directly access HTTPDNS through IP addresses. Multiple IP addresses are available. In this section, 47.74.222.190 is used as an example to describe how to access HTTPDNS.

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

   HTTP URL: http://47.74.222.190/{account_id}/d

   HTTPS URL: https://47.74.222.190/{account_id}/d

   Note

   • Here 47.74.222.190 is an example. In actual use, the way to obtain the service IP list is to request the scheduling service interface, such as http://8.219.58.10/ {account_Id}/ss, please refer to Service IP address scheduling operation.

   • Replace {account_id} with your account ID. You can obtain this ID in the HTTPDNS console.

   The following table describes the parameters in the URL.

   Parameter	Required	Description
   host	Yes	The domain name that you want to resolve.
   ip	No	The source IP address. If this parameter is not specified, the source IP address of the request is used by default.
   query	No	The type of the IP address that you want to resolve the domain name to. Valid values: 6 (IPv6) and 4 (IPv4). Default value: 4.

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

   Sample requests:

   • Example 1 (default source): http://47.74.222.190/902379/d?host=www.aliyun.com

   • Example 2 (specified source): http://47.74.222.190/902379/d?host=www.aliyun.com&ip=42.120.74.196

   • Example 3 (specified resolution type): http://47.74.222.190/902379/d?host=www.aliyun.com&ip=219.242.0.1&query=4,6

   • Example 4 (IPv6): http://[240b:4000:f10::178]/902379/d?host=www.aliyun.com&ip=219.242.0.1&query=4,6

2. IP addresses of HTTPDNS

   Considering the risk of IP addresses possibly being attacked, HTTPDNS provides multiple IP addresses to ensure service availability. If an IP address is unavailable due to exceptions, you can use other IP addresses to retry accessing HTTPDNS. 47.74.222.190 used in the preceding section is one of the IP addresses.

   HTTPDNS provides an Android SDK and an iOS SDK. In the SDKs, the IP rotation and retry on error policies are implemented. In most cases, we recommend that you integrate the SDKs, which eliminates the need to manually call the HTTP API.

   If you cannot use the SDKs in special scenarios and need to directly use the HTTP API, submit a ticket. The technical support personnel will provide you with multiple IP addresses and related security suggestions based on your business scenario.

API response

• Successful requests

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

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

  The following table describes the parameters in the response result.

  Parameter	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. The TTL value of the domain name is configured on an authoritative 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.

  The returned ips parameter may be empty. In this case, no IP addresses are obtained for the domain name. This can be caused by the following reasons:

  • The domain name is not added in the HTTPDNS console. Go to the HTTPDNS console to add the domain name.

  • The IP addresses do not exist, the domain name is not registered, or no IP address is configured.

  The following code shows an example with an empty ips parameter:

  {
  "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 the HTTPDNS service to obtain the latest resolved IP addresses.

• Failed requests

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

  Example:

  {
  "code":"MissingArgument"
  }

  The following table describes the error codes.

  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.
  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	Indicates that an internal error on the server occurred.

Error handling

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

• Asynchronous requests

  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 LocalDNS resolution and start another thread to asynchronously initiate a HTTPDNS resolution request. This way, the cache is updated and the TTL can be hit when the domain name is subsequently resolved.

• Retries

  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 by using the HTTPDNS service, you must use a degraded resolution method. In this case, use LocalDNS 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.

Fast access

To facilitate the access of mobile users, HTTPDNS provides demos and SDKs for Android and iOS.

• Run the demos

  The demos are based on the API operations of HTTPDNS and demonstrate how to access HTTPDNS. You can make modifications based on your business requirements.

  The source code of the demos is hosted in the project of Alibaba Cloud mobile service demos on GitHub. You can visit the following links to obtain the source code:

  • HTTPDNS Android Demo

  • HTTPDNS iOS Demo

• Integrate the SDKs

  The SDKs encapsulate the underlying API operations of HTTPDNS and provide you with an available library that allows you to quickly access HTTPDNS.

  For information about how to obtain and use the SDKs, see the following topics:

  • Developer guide of HTTPDNS SDK for Android

  • Install HTTPDNS SDK for iOS

Precautions

• 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 field 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 solve this problem, 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, www.example.com that you want to visit is resolved to 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);

• Cookie header

  Some 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 can cause problems in the management and use of cookies. Therefore, you must disable the automatic cookie management feature. By default, this feature is disabled.

• When you 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:

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

  • Modify the certificate checking logic on the server. For more information, see Connect an Android app to an IP address over HTTPS or Connect an iOS app to an IP address over HTTPS (including scenarios in which SNI is required).

• When you 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:

  • Use native DNS resolution to avoid this issue.

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

  The X-Online-Host private field is used to solve similar problems for WAP gateways. The following code shows an example.

  Destination URL: http://www.example.com/product/oss/
  IP address that www.example.com is resolved to by 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 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 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 call setRequestProperty to configure the X-Online-Host request header.

  In most scenarios, we recommend that you disable HTTPDNS in proxy mode.

  • For information about a more secure authenticated mode for access, see Authenticate resolving requests.