HTTPDNS:how to obtain the resolution service endpoint

Scenarios

HTTPDNS offers an official SDK for domain name resolution services. The SDK handles the automatic retrieval, updating, and maintenance of service IP addresses, allowing you to complete the resolution by invoking the interface. However, in some scenarios, you might prefer not to integrate the SDK and instead use the official HTTPDNS HTTP API directly. In such cases, it's important to know how to obtain, update, and maintain the service node IP address list to ensure nearby scheduling and high availability for domain name resolution.

To facilitate this, we provide a scheduling interface in the form of an HTTP API. Before using HTTPDNS for resolution, you should invoke this interface to retrieve the service endpoint. The process is as follows:

1. Embed a default list of HTTPDNS Startup IP addresses in your application. Upon startup, select any IP (or domain name) from this list to initiate a request and invoke the scheduling interface.

2. The scheduling interface will identify the nearest and most reliable HTTPDNS service node based on the request's source address.

3. The scheduling interface returns a list of service IP addresses for the identified node in the response.

4. Select any IP address from this list to invoke the resolution interface for domain name resolution.

5. If the application restarts or a network switch occurs, you can use the scheduling interface to initiate a scheduling request again to obtain a new service address list.

By following these steps, you can maintain an updated and nearby list of HTTPDNS service addresses with high availability.

Using the logic described, you can retrieve, refresh, and manage a list of nearby, highly available HTTPDNS service addresses.

Glossary

Scheduling service: A service that provides the scheduling interface mentioned in this document. It returns the service IP address list and other relevant scheduling information based on the source IP of the request. Typically, you only need to consider the returned IP address list.

Resolution service: The HTTPDNS resolution service interface that resolves domain names to their corresponding IP addresses. For more information, see the single domain name resolution document.

Startup IP: The initial IP (or domain name) used to access the scheduling service. It is utilized to retrieve the latest Service IP address list.

Service IP: The IP used to access the resolution service for domain name resolution.

Access process

The access process is illustrated below:

1. Review the HTTPDNS startup IP list.

   Note

   The Startup IP should be hardcoded into the app. Multiple Startup IPs are provided for redundancy. If a request to the scheduling interface fails, try another Startup IP.

2. Use a Startup IP to access the scheduling service and obtain the Service IP list.

   Note

   • The scheduling service supports both HTTP and HTTPS. For direct HTTPS connections, refer to the section Verify Server Identity When Using HTTPS Requests for server verification details.

   • The Startup IP is exclusively for accessing the scheduling service.

3. Invoke the resolution service using a Service IP.

4. As needed, use the startup IP to access the scheduling service, update the service IP list, and ensure its validity.

   Note

   • (Recommended) Update the service IP address list upon a cold start.

   • (Recommended) Update the service IP address list when switching network environments.

   • (Recommended) Refresh the service IP address list at least every 8 hours.

   • Update immediately if the service IP list fails to resolve after retries.

Specific description of the scheduling interface

URL: https://{startup IP}/{account_id}/ss

Request Method: GET

Optional Parameter Description One:

Optional Parameter Description Two:

Verify Server Identity When Using HTTPS Requests:

• When using HTTPS to request the scheduling interface, a valid certificate with the hostname 203.107.1.1 will be provided, regardless of the requested IP. Manually ignore the hostname error in the certificate and verify that the certificate's hostname is 203.107.1.1.

• The scheduling interface will include a signature in the X-Checksum-HmacMD5 field of the response header. If security is a concern, validate the returned results using this signature.

Return Result Signature Logic:

• Assuming the secretKey is IAmASecret, the random number n is 2EUenAaShVfy, the current timestamp is 1568802250, and the response content is: {"service_ip":["203.107.1.33"],"service_ipv6":["64:ff9b::cb6b:121"]};

• Request URL: http://{startup IP}/{account_id}/ss?n=2EUenAaShVfy&t=1568802250

• The signature is calculated as: hmacMD5("IAmASecret", "2EUenAaShVfy-{"service_ip":["203.107.1.33"],"service_ipv6":["64:ff9b::cb6b:121"]}-1568802250") = 3C74A498A00EEE6C5E7C599B3B882658

• The response header will then include the following: X-Checksum-HmacMD5: 3C74A498A00EEE6C5E7C599B3B882658

Return Example:

A successful request will return an HTTP status code of 200 and a JSON-formatted response. Example:

{
  "service_ip": [
    "203.107.1.33"
  ],
  "service_ipv6": [
    "64:ff9b::cb6b:121"
  ]
}

If a request fails, an HTTP status code of 4xx or 5xx and an error code will be returned in a JSON-formatted response. Example:

{
  "code": "MissingArgument"
}

Status code description