HTTPDNS:Integration guide

1. Introduction

In Client Integration Overview, you learned that HTTPDNS provides a domain name resolution service over the HTTP protocol to prevent DNS hijacking and improve resolution accuracy and stability. We recommend that you use the official SDK for integration. However, in specific scenarios, such as deep feature customization or adapting to special network environments, you may not be able to use the SDK directly. In this case, you need to implement domain name resolution on your own using the HTTP API. Integrating with HTTPDNS using the HTTP API includes the following steps:

1. Activate the HTTPDNS service

2. Add the domain names to resolve

3. Obtain development configurations, such as the Account ID and keys

4. Obtain startup endpoints

5. Call the scheduling API

6. Perform domain name resolution

7. Dynamically update the list of resolution service IP addresses

The first three steps are operations performed in the console. If you have not completed these operations, see Product usage. The last four steps are part of the HTTP API integration process. This topic describes the core concepts and process for implementing high-availability (HA) DNS using the HTTP API.

2. Core concepts

• Scheduling service: A smart routing service component that analyzes the client's source IP address for geolocation and network topology. It then returns an optimal list of resolution service nodes to achieve load balancing and nearby access.

• Resolution service: The domain name resolution execution engine. It provides standard DNS query functions to convert domain names into their corresponding IP addresses. It supports A and AAAA record types.

• Startup endpoint: A pre-configured service discovery endpoint, which can be an IP address or a domain name. It is used to establish the initial connection with the scheduling service and obtain a dynamically allocated list of resolution service nodes.

• Service IP: The address of a resolution server allocated by the scheduling service. It is an optimal node selected by a smart scheduling algorithm and is used to execute domain name resolution requests.

3. Integration steps

The HTTP API workflow includes four key steps that form a complete HA DNS resolution chain:

1. Obtain startup access points: Build multiple startup access points (IP addresses and fallback domain names) into your application to serve as the entry points for accessing the scheduling service.

2. Invoke the scheduling interface: When you start an access point, you invoke the scheduling service interface to obtain a list of nearby and healthy service IP addresses for subsequent parsing.

3. Execute domain name resolution: Use the obtained service IP to call the Domain Name Resolution API to map the domain name to an IP address.

4. Use a dynamic update mechanism: Automatically update the service IP address list under specific conditions. These conditions include app startup, network transitions, periodic updates, and resolution failures. This ensures continuous service availability.

   Note

   • Update during a cold start of the app.

   • Update when switching network environments.

   • Update at least once every 8 hours.

   • Update immediately if resolution fails for all service IP addresses in the list after retries.

The core advantage of this flow is that it achieves HA DNS resolution through multiple endpoints and dynamic scheduling:

• Multiple endpoint guarantee: Embed multiple startup endpoints to ensure service reachability. This prevents a single point of failure from affecting the entire service.

• Dynamic scheduling optimization: Dynamically obtain optimal service IP addresses through the scheduling API. This enables nearby access and failover.

This approach prevents DNS hijacking for the HTTPDNS service itself (direct IP connection, no dependency on local DNS). It also ensures high availability if some service IP addresses are blocked, are under intense DDoS attacks, or are affected by extreme natural disasters.

4. Best practices

Implementing a high-performance, high-availability (HA) HTTPDNS client based on HTTP APIs is a technically challenging task. Developers need to handle multilayer complexity, from the redundancy management of bootstrap endpoints and intelligent invocation of scheduling services to the local caching of parsed results and failover mechanisms. Each aspect requires careful design and implementation. To lower the barrier to entry and reduce implementation difficulty, you can refer to the best practices.

5. Network library adaptation

After you obtain DNS resolution results through the HTTP API, you must correctly apply these IP addresses to your application's network library. This enables direct IP connections for HTTP and HTTPS requests. To simplify integration for developers, HTTPDNS provides deep adaptation for major network libraries:

• Android platform: Complete adaptation solutions for network libraries such as OkHttp, HttpClient, and HttpURLConnection.

• iOS platform: Integration guidance for network libraries such as NSURLSession, AFNetworking, and Alamofire.

• HarmonyOS platform: Adaptation implementations for native system network APIs and major third-party network libraries.

These adaptation solutions solve the technical challenges of direct IP connections. They also handle key technical details such as HTTPS SNI, certificate validation, and Host header settings. This ensures stability and security in complex network environments.

For specific network library integration implementations, see the detailed documentation for the corresponding platform:

• Android Network Library Integration Reference

• iOS Network Library Integration Reference

• HarmonyOS Network Integration Reference

6. Summary

This topic describes the core architecture and implementation flow of high-availability HTTPDNS resolution that is based on HTTP APIs. For more information about specific implementation details, see the following topics: Start an endpoint, Scheduling service API, Domain name resolution API, and Best practice recommendations.